email.charset.md

1> **Источник:** https://python-all.ru/2.7/library/email.charset.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 18.1.6. [`email.charset`](https://python-all.ru/2.7/library/email.charset.html#module-email.charset): Представление наборов символов89Этот модуль предоставляет класс [`Charset`](https://python-all.ru/2.7/library/email.charset.html#email.charset.Charset) для представления наборов символов и преобразования наборов символов в сообщениях электронной почты, а также реестр наборов символов и несколько удобных методов для работы с этим реестром. Экземпляры [`Charset`](https://python-all.ru/2.7/library/email.charset.html#email.charset.Charset) используются в нескольких других модулях пакета [`email`](https://python-all.ru/2.7/library/email.html#module-email).1011Импортируйте этот класс из модуля [`email.charset`](https://python-all.ru/2.7/library/email.charset.html#module-email.charset).1213Новое в версии 2.2.2.1415#### `class email.charset.Charset([input_charset])`1617Сопоставляет наборы символов с их почтовыми свойствами.1819Этот класс предоставляет информацию о требованиях, предъявляемых к электронной почте для конкретного набора символов. Он также предоставляет удобные процедуры для преобразования между наборами символов при наличии соответствующих кодеков. Для заданного набора символов он делает всё возможное, чтобы предоставить информацию о том, как использовать этот набор символов в сообщении электронной почты в соответствии с RFC.2021Некоторые наборы символов должны быть закодированы с помощью quoted-printable или base64 при использовании в заголовках или телах писем. Некоторые наборы символов должны быть преобразованы полностью и не допускаются в электронной почте.2223Необязательный *input\_charset* описан ниже; он всегда приводится к нижнему регистру. После нормализации псевдонимов он также используется как ключ для поиска в реестре наборов символов, чтобы узнать кодировку заголовка, кодировку тела и кодек выходного преобразования, используемые для этого набора символов. Например, если *input\_charset* равен `iso-8859-1`, то заголовки и тела будут закодированы с помощью quoted-printable, и никакой кодек выходного преобразования не требуется. Если *input\_charset* равен `euc-jp`, то заголовки будут закодированы с помощью base64, тела не будут закодированы, но выходной текст будет преобразован из набора символов `euc-jp` в набор символов `iso-2022-jp`.2425Экземпляры [`Charset`](https://python-all.ru/2.7/library/email.charset.html#email.charset.Charset) имеют следующие атрибуты данных:2627#### `input_charset`2829Указанный исходный набор символов. Распространённые псевдонимы преобразуются в их *официальные* почтовые имена (например, `latin_1` преобразуется в `iso-8859-1`). По умолчанию – 7-битный `us-ascii`.3031#### `header_encoding`3233Если набор символов должен быть закодирован перед использованием в заголовке письма, этот атрибут будет установлен в `Charset.QP` (для quoted-printable), `Charset.BASE64` (для кодировки base64) или `Charset.SHORTEST` для наименьшего из QP или BASE64. В противном случае он будет равен `None`.3435#### `body_encoding`3637То же, что и *header\_encoding*, но описывает кодировку для тела почтового сообщения, которая действительно может отличаться от кодировки заголовка. `Charset.SHORTEST` не допускается для *body\_encoding*.3839#### `output_charset`4041Некоторые наборы символов необходимо преобразовывать перед использованием в заголовках или телах писем. Если *input\_charset* относится к таким наборам, этот атрибут будет содержать имя набора символов, в который будет преобразовано сообщение. В противном случае он будет `None`.4243#### `input_codec`4445Имя кодека Python, используемого для преобразования *input\_charset* в Unicode. Если кодек преобразования не требуется, этот атрибут будет равен `None`.4647#### `output_codec`4849Имя кодека Python, используемого для преобразования Unicode в *output\_charset*. Если кодек преобразования не требуется, этот атрибут будет иметь то же значение, что и *input\_codec*.5051Экземпляры [`Charset`](https://python-all.ru/2.7/library/email.charset.html#email.charset.Charset) также имеют следующие методы:5253#### `get_body_encoding()`5455Возвращает кодировку передачи содержимого, используемую для кодирования тела.5657Это либо строка `quoted-printable` или `base64` в зависимости от используемой кодировки, либо функция, и в этом случае следует вызвать функцию с одним аргументом – кодируемым объектом Message. Затем функция должна установить заголовок *Content-Transfer-Encoding* сама в соответствии с тем, что подходит.5859Возвращает строку `quoted-printable`, если *body\_encoding* равен `QP`, возвращает строку `base64`, если *body\_encoding* равен `BASE64`, и возвращает строку `7bit` в противном случае.6061#### `convert(s)`6263Преобразует строку *s* из *input\_codec* в *output\_codec*.6465#### `to_splittable(s)`6667Преобразует строку, возможно многобайтовую, в формат, безопасный для разделения. *s* – это строка для разделения.6869Использует *input\_codec* для попытки преобразования строки в Unicode, чтобы её можно было безопасно разделить на границах символов (даже для многобайтовых символов).7071Возвращает строку как есть, если неизвестно, как преобразовать *s* в Unicode с помощью *input\_charset*.7273Символы, которые невозможно преобразовать в Unicode, будут заменены на замещающий символ Unicode `'U+FFFD'`.7475#### `from_splittable(ustr[, to_output])`7677Преобразует разделимую строку обратно в закодированную. *ustr* – это строка Unicode для «обратного разделения».7879Этот метод использует соответствующий кодек для попытки преобразования строки из Unicode обратно в закодированный формат. Возвращает строку как есть, если она не является Unicode или если её не удалось преобразовать из Unicode.8081Символы, которые не удалось преобразовать из Unicode, будут заменены на подходящий символ (обычно `'?'`).8283Если *to\_output* равно `True` (по умолчанию), используется *output\_codec* для преобразования в кодированный формат. Если *to\_output* равно `False`, используется *input\_codec*.8485#### `get_output_charset()`8687Возвращает выходную кодировку.8889Это атрибут *output\_charset*, если он не равен `None`, в противном случае это атрибут *input\_charset*.9091#### `encoded_header_len()`9293Возвращает длину закодированной строки заголовка с правильным учётом кодирования quoted-printable или base64.9495#### `header_encode(s[, convert])`9697Кодирует строку *s* для заголовка.9899Если *convert* равно `True`, строка будет автоматически преобразована из входного набора символов в выходной. Это не подходит для многобайтовых наборов символов, у которых есть проблемы с длиной строки (многобайтовые символы должны разбиваться по символу, а не по границе байта); используйте класс [`Header`](https://python-all.ru/2.7/library/email.header.html#email.header.Header) более высокого уровня для решения этих проблем (см. [`email.header`](https://python-all.ru/2.7/library/email.header.html#module-email.header)). *convert* по умолчанию равен `False`.100101Тип кодирования (base64 или quoted-printable) будет определяться атрибутом *header\_encoding*.102103#### `body_encode(s[, convert])`104105Кодирует строку *s* для тела письма.106107Если *convert* равно `True` (по умолчанию), строка будет автоматически преобразована из входного набора символов в выходной. В отличие от [`header_encode()`](https://python-all.ru/2.7/library/email.charset.html#email.charset.Charset.header_encode), в телах писем нет проблем с границами байтов и многобайтовыми наборами символов, так что это обычно вполне безопасно.108109Тип кодирования (base64 или quoted-printable) будет определяться атрибутом *body\_encoding*.110111Класс [`Charset`](https://python-all.ru/2.7/library/email.charset.html#email.charset.Charset) также предоставляет несколько методов для поддержки стандартных операций и встроенных функций.112113#### `__str__()`114115Возвращает *input\_charset* в виде строки, приведённой к нижнему регистру. [`__repr__()`](https://python-all.ru/2.7/reference/datamodel.html#object.__repr__) – это псевдоним для [`__str__()`](https://python-all.ru/2.7/library/email.charset.html#email.charset.Charset.__str__).116117#### `__eq__(other)`118119Этот метод позволяет сравнивать два экземпляра [`Charset`](https://python-all.ru/2.7/library/email.charset.html#email.charset.Charset) на равенство.120121#### `__ne__(other)`122123Этот метод позволяет сравнивать два экземпляра [`Charset`](https://python-all.ru/2.7/library/email.charset.html#email.charset.Charset) на неравенство.124125Модуль [`email.charset`](https://python-all.ru/2.7/library/email.charset.html#module-email.charset) также предоставляет следующие функции для добавления новых записей в глобальные реестры кодировок, псевдонимов и кодеков:126127#### `email.charset.add_charset(charset[, header_enc[, body_enc[, output_charset]]])`128129Добавляет свойства кодировки в глобальный реестр.130131*charset* – это входная кодировка, и она должна быть каноническим именем набора символов.132133Необязательные параметры *header\_enc* и *body\_enc* могут быть равны `Charset.QP` для quoted-printable, `Charset.BASE64` для кодировки base64, `Charset.SHORTEST` для выбора кратчайшей из quoted-printable или base64, или `None` для отсутствия кодирования. `SHORTEST` допустим только для *header\_enc*. По умолчанию используется `None` (без кодирования).134135Необязательный параметр *output\_charset* – это кодировка, в которой должен быть вывод. Преобразования будут выполняться от входной кодировки к Unicode, а затем к выходной кодировке при вызове метода [`Charset.convert()`](https://python-all.ru/2.7/library/email.charset.html#email.charset.Charset.convert). По умолчанию вывод производится в той же кодировке, что и вход.136137Оба параметра *input\_charset* и *output\_charset* должны иметь записи кодеков Unicode в сопоставлении набора символов с кодеками модуля; используйте [`add_codec()`](https://python-all.ru/2.7/library/email.charset.html#email.charset.add_codec) для добавления кодеков, о которых модуль не знает. См. документацию модуля [`codecs`](https://python-all.ru/2.7/library/codecs.html#module-codecs) для получения дополнительной информации.138139Глобальный реестр кодировок хранится в глобальном словаре модуля `CHARSETS`.140141#### `email.charset.add_alias(alias, canonical)`142143Добавляет псевдоним кодировки. *alias* – это имя псевдонима, например `latin-1`. *canonical* – это каноническое имя кодировки, например `iso-8859-1`.144145Глобальный реестр псевдонимов кодировок хранится в глобальном словаре модуля `ALIASES`.146147#### `email.charset.add_codec(charset, codecname)`148149Добавляет кодек, который преобразует символы из заданной кодировки в Unicode и обратно.150151*charset* – это каноническое имя набора символов. *codecname* – это имя кодека Python, соответствующее второму аргументу встроенной функции [`unicode()`](https://python-all.ru/2.7/library/functions.html#unicode) или методу `encode()` строки Unicode.152