| 1 |
:mod:`!email.charset`: Representing character sets |
| 2 |
-------------------------------------------------- |
| 3 |
|
| 4 |
.. module:: email.charset |
| 5 |
:synopsis: Character Sets |
| 6 |
|
| 7 |
**Source code:** :source:`Lib/email/charset.py` |
| 8 |
|
| 9 |
-------------- |
| 10 |
|
| 11 |
This module is part of the legacy (``Compat32``) email API. In the new |
| 12 |
API only the aliases table is used. |
| 13 |
|
| 14 |
The remaining text in this section is the original documentation of the module. |
| 15 |
|
| 16 |
This module provides a class :class:`Charset` for representing character sets |
| 17 |
and character set conversions in email messages, as well as a character set |
| 18 |
registry and several convenience methods for manipulating this registry. |
| 19 |
Instances of :class:`Charset` are used in several other modules within the |
| 20 |
:mod:`email` package. |
| 21 |
|
| 22 |
Import this class from the :mod:`!email.charset` module. |
| 23 |
|
| 24 |
|
| 25 |
.. class:: Charset(input_charset=DEFAULT_CHARSET) |
| 26 |
|
| 27 |
Map character sets to their email properties. |
| 28 |
|
| 29 |
This class provides information about the requirements imposed on email for a |
| 30 |
specific character set. It also provides convenience routines for converting |
| 31 |
between character sets, given the availability of the applicable codecs. Given |
| 32 |
a character set, it will do its best to provide information on how to use that |
| 33 |
character set in an email message in an RFC-compliant way. |
| 34 |
|
| 35 |
Certain character sets must be encoded with quoted-printable or base64 when used |
| 36 |
in email headers or bodies. Certain character sets must be converted outright, |
| 37 |
and are not allowed in email. |
| 38 |
|
| 39 |
Optional *input_charset* is as described below; it is always coerced to lower |
| 40 |
case. After being alias normalized it is also used as a lookup into the |
| 41 |
registry of character sets to find out the header encoding, body encoding, and |
| 42 |
output conversion codec to be used for the character set. For example, if |
| 43 |
*input_charset* is ``iso-8859-1``, then headers and bodies will be encoded using |
| 44 |
quoted-printable and no output conversion codec is necessary. If |
| 45 |
*input_charset* is ``euc-jp``, then headers will be encoded with base64, bodies |
| 46 |
will not be encoded, but output text will be converted from the ``euc-jp`` |
| 47 |
character set to the ``iso-2022-jp`` character set. |
| 48 |
|
| 49 |
:class:`Charset` instances have the following data attributes: |
| 50 |
|
| 51 |
.. attribute:: input_charset |
| 52 |
|
| 53 |
The initial character set specified. Common aliases are converted to |
| 54 |
their *official* email names (e.g. ``latin_1`` is converted to |
| 55 |
``iso-8859-1``). Defaults to 7-bit ``us-ascii``. |
| 56 |
|
| 57 |
|
| 58 |
.. attribute:: header_encoding |
| 59 |
|
| 60 |
If the character set must be encoded before it can be used in an email |
| 61 |
header, this attribute will be set to ``charset.QP`` (for |
| 62 |
quoted-printable), ``charset.BASE64`` (for base64 encoding), or |
| 63 |
``charset.SHORTEST`` for the shortest of QP or BASE64 encoding. Otherwise, |
| 64 |
it will be ``None``. |
| 65 |
|
| 66 |
|
| 67 |
.. attribute:: body_encoding |
| 68 |
|
| 69 |
Same as *header_encoding*, but describes the encoding for the mail |
| 70 |
message's body, which indeed may be different than the header encoding. |
| 71 |
``charset.SHORTEST`` is not allowed for *body_encoding*. |
| 72 |
|
| 73 |
|
| 74 |
.. attribute:: output_charset |
| 75 |
|
| 76 |
Some character sets must be converted before they can be used in email |
| 77 |
headers or bodies. If the *input_charset* is one of them, this attribute |
| 78 |
will contain the name of the character set output will be converted to. |
| 79 |
Otherwise, it will be ``None``. |
| 80 |
|
| 81 |
|
| 82 |
.. attribute:: input_codec |
| 83 |
|
| 84 |
The name of the Python codec used to convert the *input_charset* to |
| 85 |
Unicode. If no conversion codec is necessary, this attribute will be |
| 86 |
``None``. |
| 87 |
|
| 88 |
|
| 89 |
.. attribute:: output_codec |
| 90 |
|
| 91 |
The name of the Python codec used to convert Unicode to the |
| 92 |
*output_charset*. If no conversion codec is necessary, this attribute |
| 93 |
will have the same value as the *input_codec*. |
| 94 |
|
| 95 |
|
| 96 |
:class:`Charset` instances also have the following methods: |
| 97 |
|
| 98 |
.. method:: get_body_encoding() |
| 99 |
|
| 100 |
Return the content transfer encoding used for body encoding. |
| 101 |
|
| 102 |
This is either the string ``quoted-printable`` or ``base64`` depending on |
| 103 |
the encoding used, or it is a function, in which case you should call the |
| 104 |
function with a single argument, the Message object being encoded. The |
| 105 |
function should then set the :mailheader:`Content-Transfer-Encoding` |
| 106 |
header itself to whatever is appropriate. |
| 107 |
|
| 108 |
Returns the string ``quoted-printable`` if *body_encoding* is ``QP``, |
| 109 |
returns the string ``base64`` if *body_encoding* is ``BASE64``, and |
| 110 |
returns the string ``7bit`` otherwise. |
| 111 |
|
| 112 |
|
| 113 |
.. method:: get_output_charset() |
| 114 |
|
| 115 |
Return the output character set. |
| 116 |
|
| 117 |
This is the *output_charset* attribute if that is not ``None``, otherwise |
| 118 |
it is *input_charset*. |
| 119 |
|
| 120 |
|
| 121 |
.. method:: header_encode(string) |
| 122 |
|
| 123 |
Header-encode the string *string*. |
| 124 |
|
| 125 |
The type of encoding (base64 or quoted-printable) will be based on the |
| 126 |
*header_encoding* attribute. |
| 127 |
|
| 128 |
|
| 129 |
.. method:: header_encode_lines(string, maxlengths) |
| 130 |
|
| 131 |
Header-encode a *string* by converting it first to bytes. |
| 132 |
|
| 133 |
This is similar to :meth:`header_encode` except that the string is fit |
| 134 |
into maximum line lengths as given by the argument *maxlengths*, which |
| 135 |
must be an iterator: each element returned from this iterator will provide |
| 136 |
the next maximum line length. |
| 137 |
|
| 138 |
|
| 139 |
.. method:: body_encode(string) |
| 140 |
|
| 141 |
Body-encode the string *string*. |
| 142 |
|
| 143 |
The type of encoding (base64 or quoted-printable) will be based on the |
| 144 |
*body_encoding* attribute. |
| 145 |
|
| 146 |
The :class:`Charset` class also provides a number of methods to support |
| 147 |
standard operations and built-in functions. |
| 148 |
|
| 149 |
|
| 150 |
.. method:: __str__() |
| 151 |
|
| 152 |
Returns *input_charset* as a string coerced to lower |
| 153 |
case. :meth:`!__repr__` is an alias for :meth:`!__str__`. |
| 154 |
|
| 155 |
|
| 156 |
.. method:: __eq__(other) |
| 157 |
|
| 158 |
This method allows you to compare two :class:`Charset` instances for |
| 159 |
equality. |
| 160 |
|
| 161 |
|
| 162 |
.. method:: __ne__(other) |
| 163 |
|
| 164 |
This method allows you to compare two :class:`Charset` instances for |
| 165 |
inequality. |
| 166 |
|
| 167 |
The :mod:`!email.charset` module also provides the following functions for adding |
| 168 |
new entries to the global character set, alias, and codec registries: |
| 169 |
|
| 170 |
|
| 171 |
.. function:: add_charset(charset, header_enc=None, body_enc=None, output_charset=None) |
| 172 |
|
| 173 |
Add character properties to the global registry. |
| 174 |
|
| 175 |
*charset* is the input character set, and must be the canonical name of a |
| 176 |
character set. |
| 177 |
|
| 178 |
Optional *header_enc* and *body_enc* is either ``charset.QP`` for |
| 179 |
quoted-printable, ``charset.BASE64`` for base64 encoding, |
| 180 |
``charset.SHORTEST`` for the shortest of quoted-printable or base64 encoding, |
| 181 |
or ``None`` for no encoding. ``SHORTEST`` is only valid for |
| 182 |
*header_enc*. The default is ``None`` for no encoding. |
| 183 |
|
| 184 |
Optional *output_charset* is the character set that the output should be in. |
| 185 |
Conversions will proceed from input charset, to Unicode, to the output charset |
| 186 |
when the method :meth:`Charset.convert` is called. The default is to output in |
| 187 |
the same character set as the input. |
| 188 |
|
| 189 |
Both *input_charset* and *output_charset* must have Unicode codec entries in the |
| 190 |
module's character set-to-codec mapping; use :func:`add_codec` to add codecs the |
| 191 |
module does not know about. See the :mod:`codecs` module's documentation for |
| 192 |
more information. |
| 193 |
|
| 194 |
The global character set registry is kept in the module global dictionary |
| 195 |
``CHARSETS``. |
| 196 |
|
| 197 |
|
| 198 |
.. function:: add_alias(alias, canonical) |
| 199 |
|
| 200 |
Add a character set alias. *alias* is the alias name, e.g. ``latin-1``. |
| 201 |
*canonical* is the character set's canonical name, e.g. ``iso-8859-1``. |
| 202 |
|
| 203 |
The global charset alias registry is kept in the module global dictionary |
| 204 |
``ALIASES``. |
| 205 |
|
| 206 |
|
| 207 |
.. function:: add_codec(charset, codecname) |
| 208 |
|
| 209 |
Add a codec that map characters in the given character set to and from Unicode. |
| 210 |
|
| 211 |
*charset* is the canonical name of a character set. *codecname* is the name of a |
| 212 |
Python codec, as appropriate for the second argument to the :class:`str`'s |
| 213 |
:meth:`~str.encode` method. |
| 214 |
|