email.charset.md

1> **Источник:** https://python-all.ru/3.2/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/3.2/library/email.charset.html#module-email.charset): Представление наборов символов89Этот модуль предоставляет класс [`Charset`](https://python-all.ru/3.2/library/email.charset.html#email.charset.Charset) для представления кодировок и преобразования кодировок в email-сообщениях, а также реестр кодировок и несколько удобных методов для работы с этим реестром. Экземпляры [`Charset`](https://python-all.ru/3.2/library/email.charset.html#email.charset.Charset) используются в нескольких других модулях пакета [`email`](https://python-all.ru/3.2/library/email.html#module-email).1011Этот класс импортируется из модуля [`email.charset`](https://python-all.ru/3.2/library/email.charset.html#module-email.charset).1213#### `class email.charset.Charset(input_charset=DEFAULT_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.2/library/email.charset.html#email.charset.Charset) имеют следующие атрибуты данных:2425#### `input_charset`2627Указанная исходная кодировка. Распространённые псевдонимы преобразуются в их *официальные* email-имена (например, `latin_1` преобразуется в `iso-8859-1`). По умолчанию – 7-битная `us-ascii`.2829#### `header_encoding`3031Если кодировку необходимо закодировать перед использованием в заголовке email, этот атрибут будет установлен в `Charset.QP` (для quoted-printable), `Charset.BASE64` (для кодирования base64) или `Charset.SHORTEST` для наикратчайшего из QP или BASE64. В противном случае он будет равен `None`.3233#### `body_encoding`3435Аналогично *header\_encoding*, но описывает кодировку для тела почтового сообщения, которая может отличаться от кодировки заголовка. `Charset.SHORTEST` не допускается для *body\_encoding*.3637#### `output_charset`3839Некоторые кодировки необходимо преобразовать перед использованием в заголовках или телах email. Если *input\_charset* является одной из них, этот атрибут будет содержать имя кодировки, в которую будет преобразован вывод. В противном случае он будет равен `None`.4041#### `input_codec`4243Имя кодека Python, используемого для преобразования *input\_charset* в Unicode. Если кодек преобразования не требуется, этот атрибут будет равен `None`.4445#### `output_codec`4647Имя кодека Python, используемого для преобразования Unicode в *output\_charset*. Если кодек преобразования не требуется, этот атрибут будет иметь то же значение, что и *input\_codec*.4849Экземпляры [`Charset`](https://python-all.ru/3.2/library/email.charset.html#email.charset.Charset) также имеют следующие методы:5051#### `get_body_encoding()`5253Возвращает кодировку передачи содержимого, используемую для кодирования тела.5455Это может быть строка `quoted-printable` или `base64` в зависимости от используемой кодировки, или же функция, в этом случае следует вызвать эту функцию с одним аргументом – объектом Message, который кодируется. Затем функция должна самостоятельно установить заголовок *Content-Transfer-Encoding* в соответствующее значение.5657Возвращает строку `quoted-printable`, если *body\_encoding* равен `QP`, возвращает строку `base64`, если *body\_encoding* равен `BASE64`, и возвращает строку `7bit` в противном случае.5859#### `get_output_charset()`6061Возвращает выходную кодировку.6263Это атрибут *output\_charset*, если он не равен `None`; в противном случае это *input\_charset*.6465#### `header_encode(string)`6667Кодирует строку *string* для заголовка.6869Тип кодирования (base64 или quoted-printable) будет определяться атрибутом *header\_encoding*.7071#### `header_encode_lines(string, maxlengths)`7273Кодирует строку *string* для заголовка, предварительно преобразуя её в байты.7475Это аналогично [`header_encode()`](https://python-all.ru/3.2/library/email.charset.html#email.charset.Charset.header_encode), за исключением того, что строка подгоняется под максимальную длину строк, задаваемую аргументом *maxlengths*, который должен быть итератором: каждый элемент, возвращаемый этим итератором, будет предоставлять следующую максимальную длину строки.7677#### `body_encode(string)`7879Кодирует строку *string* для тела сообщения.8081Тип кодирования (base64 или quoted-printable) будет определяться атрибутом *body\_encoding*.8283Класс [`Charset`](https://python-all.ru/3.2/library/email.charset.html#email.charset.Charset) также предоставляет ряд методов для поддержки стандартных операций и встроенных функций.8485#### `__str__()`8687Возвращает *input\_charset* в виде строки, приведённой к нижнему регистру. [`__repr__()`](https://python-all.ru/3.2/reference/datamodel.html#object.__repr__) является псевдонимом для [`__str__()`](https://python-all.ru/3.2/library/email.charset.html#email.charset.Charset.__str__).8889#### `__eq__(other)`9091Этот метод позволяет сравнивать два экземпляра [`Charset`](https://python-all.ru/3.2/library/email.charset.html#email.charset.Charset) на равенство.9293#### `__ne__(other)`9495Этот метод позволяет сравнивать два экземпляра [`Charset`](https://python-all.ru/3.2/library/email.charset.html#email.charset.Charset) на неравенство.9697Модуль [`email.charset`](https://python-all.ru/3.2/library/email.charset.html#module-email.charset) также предоставляет следующие функции для добавления новых записей в глобальные реестры наборов символов, псевдонимов и кодеков:9899#### `email.charset.add_charset(charset, header_enc=None, body_enc=None, output_charset=None)`100101Добавляет свойства кодировки в глобальный реестр.102103*charset* – это входная кодировка, и она должна быть каноническим именем набора символов.104105Необязательные параметры *header\_enc* и *body\_enc* могут быть `Charset.QP` для quoted-printable, `Charset.BASE64` для кодировки base64, `Charset.SHORTEST` для кратчайшей из quoted-printable или base64, или `None` без кодировки. `SHORTEST` допустим только для *header\_enc*. По умолчанию `None` без кодировки.106107Необязательный *output\_charset* – это набор символов, в котором должен быть вывод. Преобразования будут выполняться от входного набора символов к Unicode, затем к выходному набору, когда вызывается метод `Charset.convert()`. По умолчанию вывод осуществляется в том же наборе символов, что и входной.108109И *input\_charset*, и *output\_charset* должны иметь записи кодеков Unicode в отображении наборов символов на кодеки модуля; используйте [`add_codec()`](https://python-all.ru/3.2/library/email.charset.html#email.charset.add_codec) для добавления кодеков, о которых модуль не знает. Подробнее см. документацию модуля [`codecs`](https://python-all.ru/3.2/library/codecs.html#module-codecs).110111Глобальный реестр наборов символов хранится в глобальном словаре модуля `CHARSETS`.112113#### `email.charset.add_alias(alias, canonical)`114115Добавляет псевдоним набора символов. *alias* – это имя псевдонима, например `latin-1`. *canonical* – это каноническое имя набора символов, например `iso-8859-1`.116117Глобальный реестр псевдонимов наборов символов хранится в глобальном словаре модуля `ALIASES`.118119#### `email.charset.add_codec(charset, codecname)`120121Добавляет кодек, который преобразует символы из заданной кодировки в Unicode и обратно.122123*charset* – это каноническое имя набора символов. *codecname* – это имя кодека Python, которое используется в качестве второго аргумента метода [`str`](https://python-all.ru/3.2/library/functions.html#str) `decode()`.124