email.charset.md

1> **Источник:** https://python-all.ru/3.0/library/email.charset.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`email`](https://python-all.ru/3.0/library/email.html#module-email): Представление наборов символов89Этот модуль предоставляет класс [`Charset`](https://python-all.ru/3.0/library/email.charset.html#email.charset.Charset) для представления кодировок и преобразования кодировок в email-сообщениях, а также реестр кодировок и несколько удобных методов для работы с этим реестром. Экземпляры [`Charset`](https://python-all.ru/3.0/library/email.charset.html#email.charset.Charset) используются в нескольких других модулях пакета [`email`](https://python-all.ru/3.0/library/email.html#module-email).1011Импортируйте этот класс из модуля `email.charset`.1213#### `[email.charset.Charset]class email.charset.Charset([input_charset])`1415Сопоставляет наборы символов с их почтовыми свойствами.1617Этот класс предоставляет информацию о требованиях, предъявляемых к электронной почте для конкретного набора символов. Он также предоставляет удобные процедуры для преобразования между наборами символов при наличии соответствующих кодеков. Для заданного набора символов он делает всё возможное, чтобы предоставить информацию о том, как использовать этот набор символов в сообщении электронной почты в соответствии с RFC.1819Некоторые наборы символов должны быть закодированы с помощью quoted-printable или base64 при использовании в заголовках или телах писем. Некоторые наборы символов должны быть преобразованы полностью и не допускаются в электронной почте.2021Необязательный параметр *input\_charset* описан ниже; он всегда приводится к нижнему регистру. После нормализации псевдонимов он также используется для поиска в реестре кодировок, чтобы определить кодировку заголовка, кодировку тела и кодек выходного преобразования, которые будут использоваться для данной кодировки. Например, если *input\_charset* равен `iso-8859-1`, то заголовки и тела будут кодироваться с помощью quoted-printable, и никакой кодек выходного преобразования не требуется. Если *input\_charset* равен `euc-jp`, то заголовки будут кодироваться с помощью base64, тела не будут кодироваться, но выходной текст будет преобразован из кодировки `euc-jp` в кодировку `iso-2022-jp`.2223Экземпляры [`Charset`](https://python-all.ru/3.0/library/email.charset.html#email.charset.Charset) имеют следующие атрибуты данных:2425#### `[email.charset.Charset.input_charset]input_charset`2627Указанная исходная кодировка. Распространённые псевдонимы преобразуются в их2829*официальные*3031email-имена (например,3233`latin_1`3435преобразуется в3637`iso-8859-1`3839). По умолчанию – 7-битная4041`us-ascii`4243.4445#### `[email.charset.Charset.header_encoding]header_encoding`4647Если кодировку необходимо закодировать перед использованием в заголовке email, этот атрибут будет установлен в4849`Charset.QP`5051(для quoted-printable),5253`Charset.BASE64`5455(для кодирования base64) или5657`Charset.SHORTEST`5859для наикратчайшего из QP или BASE64. В противном случае он будет равен6061`None`6263.6465#### `[email.charset.Charset.body_encoding]body_encoding`6667Аналогично6869*header\_encoding*7071, но описывает кодировку для тела почтового сообщения, которая может отличаться от кодировки заголовка.7273`Charset.SHORTEST`7475не допускается для7677*body\_encoding*7879.8081#### `[email.charset.Charset.output_charset]output_charset`8283Некоторые наборы символов необходимо преобразовывать перед использованием в заголовках или телах email. Если8485*input\_charset*8687относится к таким, этот атрибут будет содержать имя набора символов, в который будет преобразован вывод. В противном случае он будет равен8889`None`9091.9293#### `[email.charset.Charset.input_codec]input_codec`9495Имя кодека Python, используемого для преобразования9697*input\_charset*9899в Unicode. Если кодек преобразования не требуется, этот атрибут будет равен100101`None`102103.104105#### `[email.charset.Charset.output_codec]output_codec`106107Имя кодека Python, используемого для преобразования Unicode в108109*output\_charset*110111. Если кодек преобразования не требуется, этот атрибут будет иметь то же значение, что и112113*input\_codec*114115.116117Экземпляры [`Charset`](https://python-all.ru/3.0/library/email.charset.html#email.charset.Charset) также имеют следующие методы:118119#### `[email.charset.Charset.get_body_encoding]get_body_encoding()`120121Возвращает кодировку передачи содержимого, используемую для кодирования тела.122123Это может быть строка `quoted-printable` или `base64` в зависимости от используемой кодировки, или же функция, в этом случае следует вызвать эту функцию с одним аргументом – объектом Message, который кодируется. Затем функция должна самостоятельно установить заголовок *Content-Transfer-Encoding* в соответствующее значение.124125Возвращает строку `quoted-printable`, если *body\_encoding* равен `QP`, возвращает строку `base64`, если *body\_encoding* равен `BASE64`, и возвращает строку `7bit` в противном случае.126127#### `[email.charset.Charset.convert]convert(s)`128129Преобразует строку130131*s*132133из134135*input\_codec*136137в138139*output\_codec*140141.142143#### `[email.charset.Charset.to_splittable]to_splittable(s)`144145Преобразует строку, возможно многобайтовую, в формат, безопасный для разделения. *s* – это строка для разделения.146147Использует *input\_codec* для попытки преобразования строки в Unicode, чтобы её можно было безопасно разделить на границах символов (даже для многобайтовых символов).148149Возвращает строку как есть, если неизвестно, как преобразовать *s* в Unicode с помощью *input\_charset*.150151Символы, которые не удалось преобразовать в Unicode, будут заменены на символ замены Unicode `'U+FFFD'`.152153#### `[email.charset.Charset.from_splittable]from_splittable(ustr[, to_output])`154155Преобразует разделимую строку обратно в закодированную. *ustr* – это строка Unicode для «обратного разделения».156157Этот метод использует соответствующий кодек для попытки преобразования строки из Unicode обратно в закодированный формат. Возвращает строку как есть, если она не является Unicode или если её не удалось преобразовать из Unicode.158159Символы, которые не удалось преобразовать из Unicode, будут заменены на подходящий символ (обычно `'?'`).160161Если *to\_output* равен `True` (по умолчанию), используется *output\_codec* для преобразования в закодированный формат. Если *to\_output* равен `False`, используется *input\_codec*.162163#### `[email.charset.Charset.get_output_charset]get_output_charset()`164165Возвращает выходную кодировку.166167Это атрибут *output\_charset*, если он не равен `None`; в противном случае это *input\_charset*.168169#### `[email.charset.Charset.encoded_header_len]encoded_header_len()`170171Возвращает длину закодированной строки заголовка с правильным учётом кодирования quoted-printable или base64.172173#### `[email.charset.Charset.header_encode]header_encode(s[, convert])`174175Кодирует строку *s* для заголовка.176177Если *convert* равен `True`, строка будет автоматически преобразована из входной кодировки в выходную. Это не полезно для многобайтовых наборов символов, у которых есть проблемы с длиной строки (многобайтовые символы должны разделяться по границе символа, а не байта). Используйте класс более высокого уровня `Header` для решения этих проблем (см. [`email.header`](https://python-all.ru/3.0/library/email.header.html#module-email.header)). Параметр *convert* по умолчанию равен `False`.178179Тип кодирования (base64 или quoted-printable) будет определяться атрибутом *header\_encoding*.180181#### `[email.charset.Charset.body_encode]body_encode(s[, convert])`182183Кодирует строку *s* для тела письма.184185Если *convert* равен `True` (по умолчанию), строка будет автоматически преобразована из входной кодировки в выходную. В отличие от [`header_encode()`](https://python-all.ru/3.0/library/email.charset.html#email.charset.Charset.header_encode), в телах писем нет проблем с границами байтов и многобайтовыми кодировками, поэтому это обычно вполне безопасно.186187Тип кодирования (base64 или quoted-printable) будет определяться атрибутом *body\_encoding*.188189Класс [`Charset`](https://python-all.ru/3.0/library/email.charset.html#email.charset.Charset) также предоставляет ряд методов для поддержки стандартных операций и встроенных функций.190191#### `[email.charset.Charset.__str__]__str__()`192193Возвращает194195*input\_charset*196197в виде строки, приведённой к нижнему регистру.198199[`__repr__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__repr__)200201является псевдонимом для202203[`__str__()`](https://python-all.ru/3.0/library/email.charset.html#email.charset.Charset.__str__)204205.206207#### `[email.charset.Charset.__eq__]__eq__(other)`208209Этот метод позволяет сравнивать два экземпляра210211[`Charset`](https://python-all.ru/3.0/library/email.charset.html#email.charset.Charset)212213на равенство.214215#### `[email.charset.Charset.__ne__]__ne__(other)`216217Этот метод позволяет сравнивать два экземпляра218219[`Charset`](https://python-all.ru/3.0/library/email.charset.html#email.charset.Charset)220221на неравенство.222223Модуль `email.charset` также предоставляет следующие функции для добавления новых записей в глобальные реестры наборов символов, псевдонимов и кодеков:224225#### `[email.charset.add_charset]email.charset.add_charset(charset[, header_enc[, body_enc[, output_charset]]])`226227Добавляет свойства кодировки в глобальный реестр.228229*charset* – это входная кодировка, и она должна быть каноническим именем набора символов.230231Необязательные параметры *header\_enc* и *body\_enc* могут быть `Charset.QP` для quoted-printable, `Charset.BASE64` для кодировки base64, `Charset.SHORTEST` для кратчайшей из quoted-printable или base64, или `None` без кодировки. `SHORTEST` допустим только для *header\_enc*. По умолчанию `None` без кодировки.232233Необязательный *output\_charset* – это кодировка, в которой должен быть вывод. Преобразование будет идти от входной кодировки к Unicode, а затем к выходной кодировке при вызове метода [`Charset.convert()`](https://python-all.ru/3.0/library/email.charset.html#email.charset.Charset.convert). По умолчанию вывод производится в той же кодировке, что и входная.234235И *input\_charset*, и *output\_charset* должны иметь записи кодеков Unicode в отображении наборов символов на кодеки модуля; используйте [`add_codec()`](https://python-all.ru/3.0/library/email.charset.html#email.charset.add_codec) для добавления кодеков, о которых модуль не знает. Подробнее см. документацию модуля [`codecs`](https://python-all.ru/3.0/library/codecs.html#module-codecs).236237Глобальный реестр наборов символов хранится в глобальном словаре модуля `CHARSETS`.238239#### `[email.charset.add_alias]email.charset.add_alias(alias, canonical)`240241Добавляет псевдоним набора символов. *alias* – это имя псевдонима, например `latin-1`. *canonical* – это каноническое имя набора символов, например `iso-8859-1`.242243Глобальный реестр псевдонимов наборов символов хранится в глобальном словаре модуля `ALIASES`.244245#### `[email.charset.add_codec]email.charset.add_codec(charset, codecname)`246247Добавляет кодек, который преобразует символы из заданной кодировки в Unicode и обратно.248249*charset* – это каноническое имя набора символов. *codecname* – это имя кодека Python, которое используется в качестве второго аргумента метода [`str`](https://python-all.ru/3.0/library/functions.html#str) `decode()`.250