rest25/library/email.charset.rst => rest262/library/email.charset.rst
n1+:mod:`email`: Representing character sets
2+-----------------------------------------
3+ 
1.. module:: email.charset
2   :synopsis: Character Sets
3
4
5This module provides a class :class:`Charset` for representing character sets
6and character set conversions in email messages, as well as a character set
7registry and several convenience methods for manipulating this registry.
8Instances of :class:`Charset` are used in several other modules within the
32   registry of character sets to find out the header encoding, body encoding, and
33   output conversion codec to be used for the character set.  For example, if
34   *input_charset* is ``iso-8859-1``, then headers and bodies will be encoded using
35   quoted-printable and no output conversion codec is necessary.  If
36   *input_charset* is ``euc-jp``, then headers will be encoded with base64, bodies
37   will not be encoded, but output text will be converted from the ``euc-jp``
38   character set to the ``iso-2022-jp`` character set.
39
n40-:class:`Charset` instances have the following data attributes:
n43+   :class:`Charset` instances have the following data attributes:
41
42
n43-.. data:: input_charset
n46+   .. attribute:: input_charset
44
n45-   The initial character set specified.  Common aliases are converted to their
n48+      The initial character set specified.  Common aliases are converted to
46-   *official* email names (e.g. ``latin_1`` is converted to ``iso-8859-1``).
49+      their *official* email names (e.g. ``latin_1`` is converted to
47-   Defaults to 7-bit ``us-ascii``.
50+      ``iso-8859-1``).  Defaults to 7-bit ``us-ascii``.
48
49
n50-.. data:: header_encoding
n53+   .. attribute:: header_encoding
51
n52-   If the character set must be encoded before it can be used in an email header,
n55+      If the character set must be encoded before it can be used in an email
53-   this attribute will be set to ``Charset.QP`` (for quoted-printable),
56+      header, this attribute will be set to ``Charset.QP`` (for
54-   ``Charset.BASE64`` (for base64 encoding), or ``Charset.SHORTEST`` for the
57+      quoted-printable), ``Charset.BASE64`` (for base64 encoding), or
55-   shortest of QP or BASE64 encoding. Otherwise, it will be ``None``.
58+      ``Charset.SHORTEST`` for the shortest of QP or BASE64 encoding. Otherwise,
59+      it will be ``None``.
56
57
n58-.. data:: body_encoding
n62+   .. attribute:: body_encoding
59
n60-   Same as *header_encoding*, but describes the encoding for the mail message's
n64+      Same as *header_encoding*, but describes the encoding for the mail
61-   body, which indeed may be different than the header encoding.
65+      message's body, which indeed may be different than the header encoding.
62-   ``Charset.SHORTEST`` is not allowed for *body_encoding*.
66+      ``Charset.SHORTEST`` is not allowed for *body_encoding*.
63
64
n65-.. data:: output_charset
n69+   .. attribute:: output_charset
66
n67-   Some character sets must be converted before they can be used in email headers
n71+      Some character sets must be converted before they can be used in email headers
68-   or bodies.  If the *input_charset* is one of them, this attribute will contain
72+      or bodies.  If the *input_charset* is one of them, this attribute will
69-   the name of the character set output will be converted to.  Otherwise, it will
73+      contain the name of the character set output will be converted to.  Otherwise, it will
70-   be ``None``.
74+      be ``None``.
71
72
n73-.. data:: input_codec
n77+   .. attribute:: input_codec
74
n75-   The name of the Python codec used to convert the *input_charset* to Unicode.  If
n79+      The name of the Python codec used to convert the *input_charset* to
76-   no conversion codec is necessary, this attribute will be ``None``.
80+      Unicode.  If no conversion codec is necessary, this attribute will be
81+      ``None``.
77
78
n79-.. data:: output_codec
n84+   .. attribute:: output_codec
80
n81-   The name of the Python codec used to convert Unicode to the *output_charset*.
n86+      The name of the Python codec used to convert Unicode to the
82-   If no conversion codec is necessary, this attribute will have the same value as
87+      *output_charset*.  If no conversion codec is necessary, this attribute
83-   the *input_codec*.
88+      will have the same value as the *input_codec*.
84
n85-:class:`Charset` instances also have the following methods:
n90+   :class:`Charset` instances also have the following methods:
86
87
n88-.. method:: Charset.get_body_encoding()
n93+   .. method:: get_body_encoding()
89
n90-   Return the content transfer encoding used for body encoding.
n95+      Return the content transfer encoding used for body encoding.
91
n92-   This is either the string ``quoted-printable`` or ``base64`` depending on the
n97+      This is either the string ``quoted-printable`` or ``base64`` depending on
93-   encoding used, or it is a function, in which case you should call the function
98+      the encoding used, or it is a function, in which case you should call the
94-   with a single argument, the Message object being encoded.  The function should
99+      function with a single argument, the Message object being encoded.  The
95-   then set the :mailheader:`Content-Transfer-Encoding` header itself to whatever
100+      function should then set the :mailheader:`Content-Transfer-Encoding`
96-   is appropriate.
101+      header itself to whatever is appropriate.
97
n98-   Returns the string ``quoted-printable`` if *body_encoding* is ``QP``, returns
n103+      Returns the string ``quoted-printable`` if *body_encoding* is ``QP``,
99-   the string ``base64`` if *body_encoding* is ``BASE64``, and returns the string
104+      returns the string ``base64`` if *body_encoding* is ``BASE64``, and
100-   ``7bit`` otherwise.
105+      returns the string ``7bit`` otherwise.
101
102
n103-.. method:: Charset.convert(s)
n108+   .. method:: convert(s)
104
n105-   Convert the string *s* from the *input_codec* to the *output_codec*.
n110+      Convert the string *s* from the *input_codec* to the *output_codec*.
106
107
n108-.. method:: Charset.to_splittable(s)
n113+   .. method:: to_splittable(s)
109
n110-   Convert a possibly multibyte string to a safely splittable format. *s* is the
n115+      Convert a possibly multibyte string to a safely splittable format. *s* is
111-   string to split.
116+      the string to split.
112
n113-   Uses the *input_codec* to try and convert the string to Unicode, so it can be
n118+      Uses the *input_codec* to try and convert the string to Unicode, so it can
114-   safely split on character boundaries (even for multibyte characters).
119+      be safely split on character boundaries (even for multibyte characters).
115
n116-   Returns the string as-is if it isn't known how to convert *s* to Unicode with
n121+      Returns the string as-is if it isn't known how to convert *s* to Unicode
117-   the *input_charset*.
122+      with the *input_charset*.
118
n119-   Characters that could not be converted to Unicode will be replaced with the
n124+      Characters that could not be converted to Unicode will be replaced with
120-   Unicode replacement character ``'U+FFFD'``.
125+      the Unicode replacement character ``'U+FFFD'``.
121
122
n123-.. method:: Charset.from_splittable(ustr[, to_output])
n128+   .. method:: from_splittable(ustr[, to_output])
124
n125-   Convert a splittable string back into an encoded string.  *ustr* is a Unicode
n130+      Convert a splittable string back into an encoded string.  *ustr* is a
126-   string to "unsplit".
131+      Unicode string to "unsplit".
127
n128-   This method uses the proper codec to try and convert the string from Unicode
n133+      This method uses the proper codec to try and convert the string from
129-   back into an encoded format.  Return the string as-is if it is not Unicode, or
134+      Unicode back into an encoded format.  Return the string as-is if it is not
130-   if it could not be converted from Unicode.
135+      Unicode, or if it could not be converted from Unicode.
131
n132-   Characters that could not be converted from Unicode will be replaced with an
n137+      Characters that could not be converted from Unicode will be replaced with
133-   appropriate character (usually ``'?'``).
138+      an appropriate character (usually ``'?'``).
134
n135-   If *to_output* is ``True`` (the default), uses *output_codec* to convert to an
n140+      If *to_output* is ``True`` (the default), uses *output_codec* to convert
136-   encoded format.  If *to_output* is ``False``, it uses *input_codec*.
141+      to an encoded format.  If *to_output* is ``False``, it uses *input_codec*.
137
138
n139-.. method:: Charset.get_output_charset()
n144+   .. method:: get_output_charset()
140
n141-   Return the output character set.
n146+      Return the output character set.
142
n143-   This is the *output_charset* attribute if that is not ``None``, otherwise it is
n148+      This is the *output_charset* attribute if that is not ``None``, otherwise
144-   *input_charset*.
149+      it is *input_charset*.
145
146
n147-.. method:: Charset.encoded_header_len()
n152+   .. method:: encoded_header_len()
148
n149-   Return the length of the encoded header string, properly calculating for quoted-
n154+      Return the length of the encoded header string, properly calculating for
150-   printable or base64 encoding.
155+      quoted-printable or base64 encoding.
151
152
n153-.. method:: Charset.header_encode(s[, convert])
n158+   .. method:: header_encode(s[, convert])
154
n155-   Header-encode the string *s*.
n160+      Header-encode the string *s*.
156
n157-   If *convert* is ``True``, the string will be converted from the input charset to
n162+      If *convert* is ``True``, the string will be converted from the input
158-   the output charset automatically.  This is not useful for multibyte character
163+      charset to the output charset automatically.  This is not useful for
159-   sets, which have line length issues (multibyte characters must be split on a
164+      multibyte character sets, which have line length issues (multibyte
160-   character, not a byte boundary); use the higher-level :class:`Header` class to
165+      characters must be split on a character, not a byte boundary); use the
161-   deal with these issues (see :mod:`email.header`).  *convert* defaults to
166+      higher-level :class:`Header` class to deal with these issues (see
162-   ``False``.
167+      :mod:`email.header`).  *convert* defaults to ``False``.
163
n164-   The type of encoding (base64 or quoted-printable) will be based on the
n169+      The type of encoding (base64 or quoted-printable) will be based on the
165-   *header_encoding* attribute.
170+      *header_encoding* attribute.
166
167
n168-.. method:: Charset.body_encode(s[, convert])
n173+   .. method:: body_encode(s[, convert])
169
n170-   Body-encode the string *s*.
n175+      Body-encode the string *s*.
171
n172-   If *convert* is ``True`` (the default), the string will be converted from the
n177+      If *convert* is ``True`` (the default), the string will be converted from
173-   input charset to output charset automatically. Unlike :meth:`header_encode`,
178+      the input charset to output charset automatically. Unlike
174-   there are no issues with byte boundaries and multibyte charsets in email bodies,
179+      :meth:`header_encode`, there are no issues with byte boundaries and
175-   so this is usually pretty safe.
180+      multibyte charsets in email bodies, so this is usually pretty safe.
176
n177-   The type of encoding (base64 or quoted-printable) will be based on the
n182+      The type of encoding (base64 or quoted-printable) will be based on the
178-   *body_encoding* attribute.
183+      *body_encoding* attribute.
179
n180-The :class:`Charset` class also provides a number of methods to support standard
n185+   The :class:`Charset` class also provides a number of methods to support
181-operations and built-in functions.
186+   standard operations and built-in functions.
182
183
n184-.. method:: Charset.__str__()
n189+   .. method:: __str__()
185
n186-   Returns *input_charset* as a string coerced to lower case. :meth:`__repr__` is
n191+      Returns *input_charset* as a string coerced to lower
187-   an alias for :meth:`__str__`.
192+      case. :meth:`__repr__` is an alias for :meth:`__str__`.
188
189
n190-.. method:: Charset.__eq__(other)
n195+   .. method:: __eq__(other)
191
n192-   This method allows you to compare two :class:`Charset` instances for equality.
n197+      This method allows you to compare two :class:`Charset` instances for
198+      equality.
193
194
n195-.. method:: Header.__ne__(other)
n201+   .. method:: __ne__(other)
196
n197-   This method allows you to compare two :class:`Charset` instances for inequality.
n203+      This method allows you to compare two :class:`Charset` instances for
204+      inequality.
198
199The :mod:`email.charset` module also provides the following functions for adding
200new entries to the global character set, alias, and codec registries:
201
202
203.. function:: add_charset(charset[, header_enc[, body_enc[, output_charset]]])
204
205   Add character properties to the global registry.
206
207   *charset* is the input character set, and must be the canonical name of a
208   character set.
209
t210-   Optional *header_enc* and *body_enc* is either ``Charset.QP`` for quoted-
t217+   Optional *header_enc* and *body_enc* is either ``Charset.QP`` for
211-   printable, ``Charset.BASE64`` for base64 encoding, ``Charset.SHORTEST`` for the
218+   quoted-printable, ``Charset.BASE64`` for base64 encoding,
212-   shortest of quoted-printable or base64 encoding, or ``None`` for no encoding.
219+   ``Charset.SHORTEST`` for the shortest of quoted-printable or base64 encoding,
213-   ``SHORTEST`` is only valid for *header_enc*. The default is ``None`` for no
220+   or ``None`` for no encoding.  ``SHORTEST`` is only valid for
214-   encoding.
221+   *header_enc*. The default is ``None`` for no encoding.
215
216   Optional *output_charset* is the character set that the output should be in.
217   Conversions will proceed from input charset, to Unicode, to the output charset
218   when the method :meth:`Charset.convert` is called.  The default is to output in
219   the same character set as the input.
220
221   Both *input_charset* and *output_charset* must have Unicode codec entries in the
222   module's character set-to-codec mapping; use :func:`add_codec` to add codecs the
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op