`email.header.md`

136 строк · 18.2 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.13/library/email.header.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `email.header`: Интернационализированные заголовки89**Исходный код:** [Lib/email/header.py](https://python-all.ru/src/3.13/Lib/email/header.py)1011---1213Этот модуль является частью устаревшего (`Compat32`) API email. В текущем API кодирование и декодирование заголовков обрабатывается прозрачно через API, подобный словарю, класса [`EmailMessage`](https://python-all.ru/3.13/library/email.message.html#email.message.EmailMessage). В дополнение к использованию в устаревшем коде, этот модуль может быть полезен в приложениях, которым требуется полный контроль над наборами символов, используемыми при кодировании заголовков.1415Оставшийся текст в этом разделе является оригинальной документацией модуля.1617[**RFC 2822**](https://python-all.ru/3.13/library/email.header.html) – это базовый стандарт, описывающий формат email-сообщений. Он происходит от более старого стандарта [**RFC 822**](https://python-all.ru/3.13/library/email.header.html), который получил широкое распространение в то время, когда большинство писем состояло только из символов ASCII. [**RFC 2822**](https://python-all.ru/3.13/library/email.header.html) – это спецификация, написанная в предположении, что email содержит только 7-битные символы ASCII.1819Конечно, с распространением email по всему миру он стал интернационализированным, так что теперь в email-сообщениях можно использовать наборы символов, специфичные для языка. Базовый стандарт по-прежнему требует, чтобы email-сообщения передавались только с использованием 7-битных символов ASCII, поэтому был написан ряд RFC, описывающих, как кодировать email, содержащий не-ASCII символы, в формат, совместимый с [**RFC 2822**](https://python-all.ru/3.13/library/email.header.html). Эти RFC включают [**RFC 2045**](https://python-all.ru/3.13/library/email.header.html), [**RFC 2046**](https://python-all.ru/3.13/library/email.header.html), [**RFC 2047**](https://python-all.ru/3.13/library/email.header.html) и [**RFC 2231**](https://python-all.ru/3.13/library/email.header.html). Пакет [`email`](https://python-all.ru/3.13/library/email.html#module-email) поддерживает эти стандарты в своих модулях `email.header` и [`email.charset`](https://python-all.ru/3.13/library/email.charset.html#module-email.charset).2021Если вы хотите включить не-ASCII символы в заголовки email, например, в поля *Subject* или *To*, следует использовать класс [`Header`](https://python-all.ru/3.13/library/email.header.html#email.header.Header) и присвоить поле в объекте [`Message`](https://python-all.ru/3.13/library/email.compat32-message.html#email.message.Message) экземпляру `Header` вместо использования строки для значения заголовка. Импортируйте класс `Header` из модуля `email.header`. Например:2223```python24>>> from email.message import Message25>>> from email.header import Header26>>> msg = Message()27>>> h = Header('p\xf6stal', 'iso-8859-1')28>>> msg['Subject'] = h29>>> msg.as_string()30'Subject: =?iso-8859-1?q?p=F6stal?=\n\n'31```3233Обратите внимание, как мы хотели, чтобы поле *Subject* содержало не-ASCII символ? Мы сделали это, создав экземпляр [`Header`](https://python-all.ru/3.13/library/email.header.html#email.header.Header) и передав набор символов, в котором была закодирована байтовая строка. Когда последующий экземпляр [`Message`](https://python-all.ru/3.13/library/email.compat32-message.html#email.message.Message) был преобразован в плоскую строку, поле *Subject* было должным образом закодировано с помощью [**RFC 2047**](https://python-all.ru/3.13/library/email.header.html). Почтовые программы, поддерживающие MIME, покажут этот заголовок, используя встроенный символ ISO-8859-1.3435Вот описание класса [`Header`](https://python-all.ru/3.13/library/email.header.html#email.header.Header):3637#### `class email.header.Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')`3839Создаёт заголовок, совместимый с MIME, который может содержать строки в разных наборах символов.4041Необязательный параметр *s* – это начальное значение заголовка. Если `None` (по умолчанию), начальное значение заголовка не установлено. Позже можно добавлять данные в заголовок с помощью вызовов метода [`append()`](https://python-all.ru/3.13/library/email.header.html#email.header.Header.append). *s* может быть экземпляром [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes) или [`str`](https://python-all.ru/3.13/library/stdtypes.html#str), но смотрите документацию `append()` о семантике.4243Необязательный параметр *charset* служит двум целям: он имеет то же значение, что и аргумент *charset* метода [`append()`](https://python-all.ru/3.13/library/email.header.html#email.header.Header.append). Он также устанавливает набор символов по умолчанию для всех последующих вызовов `append()`, в которых опущен аргумент *charset*. Если *charset* не указан в конструкторе (по умолчанию), набор символов `us-ascii` используется как начальный набор символов для *s*, так и как набор по умолчанию для последующих вызовов `append()`.4445Максимальная длина строки может быть задана явно через *maxlinelen*. Чтобы разделить первую строку на более короткую (с учётом заголовка поля, который не включён в *s*, например, *Subject*), передайте имя поля в *header\_name*. Значение по умолчанию *maxlinelen* – 78, а значение по умолчанию для *header\_name* – `None`, то есть оно не учитывается для первой строки длинного разделённого заголовка.4647Необязательный параметр *continuation\_ws* должен быть пробельным символом для переноса, совместимым с [**RFC 2822**](https://python-all.ru/3.13/library/email.header.html), и обычно это пробел или символ табуляции. Этот символ будет добавляться в начало строк продолжения. По умолчанию *continuation\_ws* – это одиночный пробел.4849Необязательный параметр *errors* передаётся напрямую методу [`append()`](https://python-all.ru/3.13/library/email.header.html#email.header.Header.append).5051#### `append(s, charset=None, errors='strict')`5253Добавляет строку *s* к MIME-заголовку.5455Необязательный *charset*, если указан, должен быть экземпляром [`Charset`](https://python-all.ru/3.13/library/email.charset.html#email.charset.Charset) (см. [`email.charset`](https://python-all.ru/3.13/library/email.charset.html#module-email.charset)) или именем набора символов, который будет преобразован в экземпляр `Charset`. Значение `None` (по умолчанию) означает, что используется *charset*, указанный в конструкторе.5657*s* может быть экземпляром [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes) или [`str`](https://python-all.ru/3.13/library/stdtypes.html#str). Если это экземпляр `bytes`, то *charset* – это кодировка этой байтовой строки, и будет возбуждено исключение [`UnicodeError`](https://python-all.ru/3.13/library/exceptions.html#UnicodeError), если строка не может быть декодирована с этим набором символов.5859Если *s* является экземпляром [`str`](https://python-all.ru/3.13/library/stdtypes.html#str), то *charset* – это подсказка, указывающая набор символов для символов в строке.6061В любом случае, при создании заголовка, совместимого с [**RFC 2822**](https://python-all.ru/3.13/library/email.header.html), с использованием правил [**RFC 2047**](https://python-all.ru/3.13/library/email.header.html), строка будет закодирована с помощью выходного кодека набора символов. Если строка не может быть закодирована с помощью выходного кодека, будет возбуждено исключение UnicodeError.6263Необязательный *errors* передаётся как аргумент errors при вызове decode, если *s* является байтовой строкой.6465#### `encode(splitchars=';, \t', maxlinelen=None, linesep='\n')`6667Кодирует заголовок сообщения в формат, соответствующий RFC, возможно, перенося длинные строки и инкапсулируя не-ASCII части в кодировки base64 или quoted-printable.6869Необязательный параметр *splitchars* – это строка, содержащая символы, которые должны получать дополнительный вес при разбиении алгоритмом во время обычного переноса заголовка. Это очень грубая поддержка ‘синтаксических разрывов более высокого уровня’ из [**RFC 2822**](https://python-all.ru/3.13/library/email.header.html): точки разрыва, перед которыми стоит символ из splitchars, предпочтительны при разбиении строк, причём символы предпочитаются в порядке их появления в строке. Пробел и табуляция могут быть включены в строку, чтобы указать предпочтение одного перед другим в качестве точки разрыва, когда другие символы разрыва не встречаются в разбиваемой строке. Splitchars не влияет на строки, закодированные по [**RFC 2047**](https://python-all.ru/3.13/library/email.header.html).7071*maxlinelen*, если указан, переопределяет значение экземпляра для максимальной длины строки.7273*linesep* задаёт символы, используемые для разделения строк свернутого заголовка. По умолчанию используется наиболее полезное значение для кода приложений Python (`\n`), но можно указать `\r\n`, чтобы создавать заголовки с разделителями строк, соответствующими RFC.7475Изменено в версии 3.2: Добавлен аргумент *linesep*.7677Класс `Header` также предоставляет ряд методов для поддержки стандартных операторов и встроенных функций.7879#### `__str__()`8081Возвращает приближение объекта `Header` в виде строки с неограниченной длиной строки. Все фрагменты преобразуются в Unicode с использованием указанной кодировки и соответствующим образом объединяются. Любые фрагменты с charset `'unknown-8bit'` декодируются как ASCII с использованием обработчика ошибок `'replace'`.8283Изменено в версии 3.2: Добавлена обработка для charset `'unknown-8bit'`.8485#### `__eq__(other)`8687Этот метод позволяет сравнивать два экземпляра `Header` на равенство.8889#### `__ne__(other)`9091Этот метод позволяет сравнивать два экземпляра `Header` на неравенство.9293Модуль `email.header` также предоставляет следующие удобные функции.9495#### `email.header.decode_header(header)`9697Декодирует значение заголовка сообщения без преобразования набора символов. Значение заголовка находится в *header*.9899По историческим причинам эта функция может возвращать одно из двух:1001011. Список пар, содержащих каждую из декодированных частей заголовка, `(decoded_bytes, charset)`, где *decoded\_bytes* всегда является экземпляром [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes), а *charset* представляет собой одно из:102103   > - Строка в нижнем регистре, содержащая имя указанного набора символов.104   > - `None` для незакодированных частей заголовка.1052. Список длины 1, содержащий пару `(string, None)`, где *string* всегда является экземпляром [`str`](https://python-all.ru/3.13/library/stdtypes.html#str).106107Исключение [`email.errors.HeaderParseError`](https://python-all.ru/3.13/library/email.errors.html#email.errors.HeaderParseError) может быть возбуждено при возникновении некоторых ошибок декодирования (например, исключения при декодировании base64).108109Вот примеры:110111```python112>>> from email.header import decode_header113>>> decode_header('=?iso-8859-1?q?p=F6stal?=')114[(b'p\xf6stal', 'iso-8859-1')]115>>> decode_header('unencoded_string')116[('unencoded_string', None)]117>>> decode_header('bar =?utf-8?B?ZsOzbw==?=')118[(b'bar ', None), (b'f\xc3\xb3o', 'utf-8')]119```120121> **Примечание**122>123> Эта функция существует только для обратной совместимости. Для нового кода рекомендуется использовать [`email.headerregistry.HeaderRegistry`](https://python-all.ru/3.13/library/email.headerregistry.html#email.headerregistry.HeaderRegistry).124125#### `email.header.make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')`126127Создаёт экземпляр [`Header`](https://python-all.ru/3.13/library/email.header.html#email.header.Header) из последовательности пар, возвращаемой функцией [`decode_header()`](https://python-all.ru/3.13/library/email.header.html#email.header.decode_header).128129Функция [`decode_header()`](https://python-all.ru/3.13/library/email.header.html#email.header.decode_header) принимает строку значения заголовка и возвращает последовательность пар формата `(decoded_string, charset)`, где *charset* – это имя набора символов.130131Эта функция принимает одну из таких последовательностей пар и возвращает экземпляр [`Header`](https://python-all.ru/3.13/library/email.header.html#email.header.Header). Необязательные параметры *maxlinelen*, *header\_name* и *continuation\_ws* такие же, как в конструкторе `Header`.132133> **Примечание**134>135> Эта функция существует только для обратной совместимости и не рекомендуется для использования в новом коде.136