`email.header.md`

116 строк · 17.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.6/library/email.header.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 19.1.11. [`email.header`](https://python-all.ru/3.6/library/email.header.html#module-email.header): Интернационализированные заголовки89**Исходный код:** [Lib/email/header.py](https://python-all.ru/src/3.6/Lib/email/header.py)1011---1213Этот модуль является частью устаревшего (`Compat32`) API email. В текущем API кодирование и декодирование заголовков обрабатывается прозрачно через API, подобный словарю, класса [`EmailMessage`](https://python-all.ru/3.6/library/email.message.html#email.message.EmailMessage). В дополнение к использованию в устаревшем коде, этот модуль может быть полезен в приложениях, которым требуется полный контроль над наборами символов, используемыми при кодировании заголовков.1415Оставшийся текст в этом разделе является оригинальной документацией модуля.1617[**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.1819Конечно, с распространением 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).2021Если вы хотите включить не-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). Например: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.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.3435Вот описание класса [`Header`](https://python-all.ru/3.6/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.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) о семантике.4243Необязательный параметр *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).4445Максимальную длину строки можно указать явно через *maxlinelen*. Чтобы первая строка разбивалась на более короткое значение (с учётом заголовка поля, который не входит в *s*, например *Subject*), передаётся имя поля в *header\_name*. Значение по умолчанию *maxlinelen* – 76, а значение по умолчанию для *header\_name* – `None`, то есть он не учитывается для первой строки длинного разбитого заголовка.4647Необязательный параметр *continuation\_ws* должен быть пробельным символом для переноса, совместимым с [**RFC 2822**](https://python-all.ru/3.6/library/email.header.html), и обычно это пробел или символ табуляции. Этот символ будет добавляться в начало строк продолжения. По умолчанию *continuation\_ws* – это одиночный пробел.4849Необязательный параметр *errors* передаётся напрямую методу [`append()`](https://python-all.ru/3.6/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.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*, указанный в конструкторе.5657*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), если строка не может быть декодирована с этим набором символов.5859Если *s* является экземпляром [`str`](https://python-all.ru/3.6/library/stdtypes.html#str), то *charset* – это подсказка, указывающая набор символов для символов в строке.6061В любом случае, при создании заголовка, совместимого с [**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.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.6/library/email.header.html): точки разбиения, перед которыми стоит символ splitchar, предпочтительны при разбиении строки, причем символы предпочтительны в порядке их появления в строке. Пробел и табуляция могут быть включены в строку, чтобы указать, следует ли отдавать предпочтение одному перед другим в качестве точки разбиения, когда другие символы splitchar не встречаются в разбиваемой строке. Параметр splitchars не влияет на строки, закодированные по [**RFC 2047**](https://python-all.ru/3.6/library/email.header.html).7071*maxlinelen*, если указан, переопределяет значение экземпляра для максимальной длины строки.7273*linesep* задаёт символы, используемые для разделения строк свернутого заголовка. По умолчанию используется наиболее полезное значение для кода приложений Python (`\n`), но можно указать `\r\n`, чтобы создавать заголовки с разделителями строк, соответствующими RFC.7475Изменено в версии 3.2: Добавлен аргумент *linesep*.7677Класс [`Header`](https://python-all.ru/3.6/library/email.header.html#email.header.Header) также предоставляет ряд методов для поддержки стандартных операторов и встроенных функций.7879#### `__str__()`8081Возвращает приближение объекта [`Header`](https://python-all.ru/3.6/library/email.header.html#email.header.Header) в виде строки с неограниченной длиной строки. Все фрагменты преобразуются в Unicode с использованием указанной кодировки и соответствующим образом объединяются. Любые фрагменты с charset `'unknown-8bit'` декодируются как ASCII с использованием обработчика ошибок `'replace'`.8283Изменено в версии 3.2: Добавлена обработка для charset `'unknown-8bit'`.8485#### `__eq__(other)`8687Этот метод позволяет сравнивать два экземпляра [`Header`](https://python-all.ru/3.6/library/email.header.html#email.header.Header) на равенство.8889#### `__ne__(other)`9091Этот метод позволяет сравнивать два экземпляра [`Header`](https://python-all.ru/3.6/library/email.header.html#email.header.Header) на неравенство.9293Модуль [`email.header`](https://python-all.ru/3.6/library/email.header.html#module-email.header) также предоставляет следующие удобные функции.9495#### `email.header.decode_header(header)`9697Декодирует значение заголовка сообщения без преобразования набора символов. Значение заголовка находится в *header*.9899Эта функция возвращает список пар `(decoded_string, charset)`, содержащих каждую из декодированных частей заголовка. *charset* равно `None` для незакодированных частей заголовка, в противном случае – это строка в нижнем регистре, содержащая имя кодировки, указанной в закодированной строке.100101Вот пример:102103```python104>>> from email.header import decode_header105>>> decode_header('=?iso-8859-1?q?p=F6stal?=')106[(b'p\xf6stal', 'iso-8859-1')]107```108109#### `email.header.make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')`110111Создаёт экземпляр [`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).112113Функция [`decode_header()`](https://python-all.ru/3.6/library/email.header.html#email.header.decode_header) принимает строку значения заголовка и возвращает последовательность пар формата `(decoded_string, charset)`, где *charset* – это имя набора символов.114115Эта функция принимает одну из таких последовательностей пар и возвращает экземпляр [`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).116