Debian Codegraph @

Doc/library/email.charset.rst

raw
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