`email.charset.md`

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