| registry of character sets to find out the header encoding, body encoding, and |
| output conversion codec to be used for the character set. For example, if |
| *input_charset* is ``iso-8859-1``, then headers and bodies will be encoded using |
| quoted-printable and no output conversion codec is necessary. If |
| *input_charset* is ``euc-jp``, then headers will be encoded with base64, bodies |
| will not be encoded, but output text will be converted from the ``euc-jp`` |
| character set to the ``iso-2022-jp`` character set. |
| |
n | :class:`Charset` instances have the following data attributes: |
n | :class:`Charset` instances have the following data attributes: |
| |
| |
n | .. data:: input_charset |
n | .. attribute:: input_charset |
| |
n | The initial character set specified. Common aliases are converted to their |
n | The initial character set specified. Common aliases are converted to |
| *official* email names (e.g. ``latin_1`` is converted to ``iso-8859-1``). |
| their *official* email names (e.g. ``latin_1`` is converted to |
| Defaults to 7-bit ``us-ascii``. |
| ``iso-8859-1``). Defaults to 7-bit ``us-ascii``. |
| |
| |
n | .. data:: header_encoding |
n | .. attribute:: header_encoding |
| |
n | If the character set must be encoded before it can be used in an email header, |
n | If the character set must be encoded before it can be used in an email |
| this attribute will be set to ``Charset.QP`` (for quoted-printable), |
| header, this attribute will be set to ``Charset.QP`` (for |
| ``Charset.BASE64`` (for base64 encoding), or ``Charset.SHORTEST`` for the |
| quoted-printable), ``Charset.BASE64`` (for base64 encoding), or |
| shortest of QP or BASE64 encoding. Otherwise, it will be ``None``. |
| ``Charset.SHORTEST`` for the shortest of QP or BASE64 encoding. Otherwise, |
| it will be ``None``. |
| |
| |
n | .. data:: body_encoding |
n | .. attribute:: body_encoding |
| |
n | Same as *header_encoding*, but describes the encoding for the mail message's |
n | Same as *header_encoding*, but describes the encoding for the mail |
| body, which indeed may be different than the header encoding. |
| message's body, which indeed may be different than the header encoding. |
| ``Charset.SHORTEST`` is not allowed for *body_encoding*. |
| ``Charset.SHORTEST`` is not allowed for *body_encoding*. |
| |
| |
n | .. data:: output_charset |
n | .. attribute:: output_charset |
| |
n | Some character sets must be converted before they can be used in email headers |
n | Some character sets must be converted before they can be used in email headers |
| or bodies. If the *input_charset* is one of them, this attribute will contain |
| or bodies. If the *input_charset* is one of them, this attribute will |
| the name of the character set output will be converted to. Otherwise, it will |
| contain the name of the character set output will be converted to. Otherwise, it will |
| be ``None``. |
| be ``None``. |
| |
| |
n | .. data:: input_codec |
n | .. attribute:: input_codec |
| |
n | The name of the Python codec used to convert the *input_charset* to Unicode. If |
n | The name of the Python codec used to convert the *input_charset* to |
| no conversion codec is necessary, this attribute will be ``None``. |
| Unicode. If no conversion codec is necessary, this attribute will be |
| ``None``. |
| |
| |
n | .. data:: output_codec |
n | .. attribute:: output_codec |
| |
n | The name of the Python codec used to convert Unicode to the *output_charset*. |
n | The name of the Python codec used to convert Unicode to the |
| If no conversion codec is necessary, this attribute will have the same value as |
| *output_charset*. If no conversion codec is necessary, this attribute |
| the *input_codec*. |
| will have the same value as the *input_codec*. |
| |
n | :class:`Charset` instances also have the following methods: |
n | :class:`Charset` instances also have the following methods: |
| |
| |
n | .. method:: Charset.get_body_encoding() |
n | .. method:: get_body_encoding() |
| |
n | Return the content transfer encoding used for body encoding. |
n | Return the content transfer encoding used for body encoding. |
| |
n | This is either the string ``quoted-printable`` or ``base64`` depending on the |
n | This is either the string ``quoted-printable`` or ``base64`` depending on |
| encoding used, or it is a function, in which case you should call the function |
| the encoding used, or it is a function, in which case you should call the |
| with a single argument, the Message object being encoded. The function should |
| function with a single argument, the Message object being encoded. The |
| then set the :mailheader:`Content-Transfer-Encoding` header itself to whatever |
| function should then set the :mailheader:`Content-Transfer-Encoding` |
| is appropriate. |
| header itself to whatever is appropriate. |
| |
n | Returns the string ``quoted-printable`` if *body_encoding* is ``QP``, returns |
n | Returns the string ``quoted-printable`` if *body_encoding* is ``QP``, |
| the string ``base64`` if *body_encoding* is ``BASE64``, and returns the string |
| returns the string ``base64`` if *body_encoding* is ``BASE64``, and |
| ``7bit`` otherwise. |
| returns the string ``7bit`` otherwise. |
| |
| |
n | .. method:: Charset.convert(s) |
n | .. method:: convert(s) |
| |
n | Convert the string *s* from the *input_codec* to the *output_codec*. |
n | Convert the string *s* from the *input_codec* to the *output_codec*. |
| |
| |
n | .. method:: Charset.to_splittable(s) |
n | .. method:: to_splittable(s) |
| |
n | Convert a possibly multibyte string to a safely splittable format. *s* is the |
n | Convert a possibly multibyte string to a safely splittable format. *s* is |
| string to split. |
| the string to split. |
| |
n | Uses the *input_codec* to try and convert the string to Unicode, so it can be |
n | Uses the *input_codec* to try and convert the string to Unicode, so it can |
| safely split on character boundaries (even for multibyte characters). |
| be safely split on character boundaries (even for multibyte characters). |
| |
n | Returns the string as-is if it isn't known how to convert *s* to Unicode with |
n | Returns the string as-is if it isn't known how to convert *s* to Unicode |
| the *input_charset*. |
| with the *input_charset*. |
| |
n | Characters that could not be converted to Unicode will be replaced with the |
n | Characters that could not be converted to Unicode will be replaced with |
| Unicode replacement character ``'U+FFFD'``. |
| the Unicode replacement character ``'U+FFFD'``. |
| |
| |
n | .. method:: Charset.from_splittable(ustr[, to_output]) |
n | .. method:: from_splittable(ustr[, to_output]) |
| |
n | Convert a splittable string back into an encoded string. *ustr* is a Unicode |
n | Convert a splittable string back into an encoded string. *ustr* is a |
| string to "unsplit". |
| Unicode string to "unsplit". |
| |
n | This method uses the proper codec to try and convert the string from Unicode |
n | This method uses the proper codec to try and convert the string from |
| back into an encoded format. Return the string as-is if it is not Unicode, or |
| Unicode back into an encoded format. Return the string as-is if it is not |
| if it could not be converted from Unicode. |
| Unicode, or if it could not be converted from Unicode. |
| |
n | Characters that could not be converted from Unicode will be replaced with an |
n | Characters that could not be converted from Unicode will be replaced with |
| appropriate character (usually ``'?'``). |
| an appropriate character (usually ``'?'``). |
| |
n | If *to_output* is ``True`` (the default), uses *output_codec* to convert to an |
n | If *to_output* is ``True`` (the default), uses *output_codec* to convert |
| encoded format. If *to_output* is ``False``, it uses *input_codec*. |
| to an encoded format. If *to_output* is ``False``, it uses *input_codec*. |
| |
| |
n | .. method:: Charset.get_output_charset() |
n | .. method:: get_output_charset() |
| |
n | Return the output character set. |
n | Return the output character set. |
| |
n | This is the *output_charset* attribute if that is not ``None``, otherwise it is |
n | This is the *output_charset* attribute if that is not ``None``, otherwise |
| *input_charset*. |
| it is *input_charset*. |
| |
| |
n | .. method:: Charset.encoded_header_len() |
n | .. method:: encoded_header_len() |
| |
n | Return the length of the encoded header string, properly calculating for quoted- |
n | Return the length of the encoded header string, properly calculating for |
| printable or base64 encoding. |
| quoted-printable or base64 encoding. |
| |
| |
n | .. method:: Charset.header_encode(s[, convert]) |
n | .. method:: header_encode(s[, convert]) |
| |
n | Header-encode the string *s*. |
n | Header-encode the string *s*. |
| |
n | If *convert* is ``True``, the string will be converted from the input charset to |
n | If *convert* is ``True``, the string will be converted from the input |
| the output charset automatically. This is not useful for multibyte character |
| charset to the output charset automatically. This is not useful for |
| sets, which have line length issues (multibyte characters must be split on a |
| multibyte character sets, which have line length issues (multibyte |
| character, not a byte boundary); use the higher-level :class:`Header` class to |
| characters must be split on a character, not a byte boundary); use the |
| deal with these issues (see :mod:`email.header`). *convert* defaults to |
| higher-level :class:`Header` class to deal with these issues (see |
| ``False``. |
| :mod:`email.header`). *convert* defaults to ``False``. |
| |
n | The type of encoding (base64 or quoted-printable) will be based on the |
n | The type of encoding (base64 or quoted-printable) will be based on the |
| *header_encoding* attribute. |
| *header_encoding* attribute. |
| |
| |
n | .. method:: Charset.body_encode(s[, convert]) |
n | .. method:: body_encode(s[, convert]) |
| |
n | Body-encode the string *s*. |
n | Body-encode the string *s*. |
| |
n | If *convert* is ``True`` (the default), the string will be converted from the |
n | If *convert* is ``True`` (the default), the string will be converted from |
| input charset to output charset automatically. Unlike :meth:`header_encode`, |
| the input charset to output charset automatically. Unlike |
| there are no issues with byte boundaries and multibyte charsets in email bodies, |
| :meth:`header_encode`, there are no issues with byte boundaries and |
| so this is usually pretty safe. |
| multibyte charsets in email bodies, so this is usually pretty safe. |
| |
n | The type of encoding (base64 or quoted-printable) will be based on the |
n | The type of encoding (base64 or quoted-printable) will be based on the |
| *body_encoding* attribute. |
| *body_encoding* attribute. |
| |
n | The :class:`Charset` class also provides a number of methods to support standard |
n | The :class:`Charset` class also provides a number of methods to support |
| operations and built-in functions. |
| standard operations and built-in functions. |
| |
| |
n | .. method:: Charset.__str__() |
n | .. method:: __str__() |
| |
n | Returns *input_charset* as a string coerced to lower case. :meth:`__repr__` is |
n | Returns *input_charset* as a string coerced to lower |
| an alias for :meth:`__str__`. |
| case. :meth:`__repr__` is an alias for :meth:`__str__`. |
| |
| |
n | .. method:: Charset.__eq__(other) |
n | .. method:: __eq__(other) |
| |
n | This method allows you to compare two :class:`Charset` instances for equality. |
n | This method allows you to compare two :class:`Charset` instances for |
| equality. |
| |
| |
n | .. method:: Header.__ne__(other) |
n | .. method:: __ne__(other) |
| |
n | This method allows you to compare two :class:`Charset` instances for inequality. |
n | This method allows you to compare two :class:`Charset` instances for |
| inequality. |
| |
| The :mod:`email.charset` module also provides the following functions for adding |
| new entries to the global character set, alias, and codec registries: |
| |
| |
| .. function:: add_charset(charset[, header_enc[, body_enc[, output_charset]]]) |
| |
| Add character properties to the global registry. |
| |
| *charset* is the input character set, and must be the canonical name of a |
| character set. |
| |
t | Optional *header_enc* and *body_enc* is either ``Charset.QP`` for quoted- |
t | Optional *header_enc* and *body_enc* is either ``Charset.QP`` for |
| printable, ``Charset.BASE64`` for base64 encoding, ``Charset.SHORTEST`` for the |
| quoted-printable, ``Charset.BASE64`` for base64 encoding, |
| shortest of quoted-printable or base64 encoding, or ``None`` for no encoding. |
| ``Charset.SHORTEST`` for the shortest of quoted-printable or base64 encoding, |
| ``SHORTEST`` is only valid for *header_enc*. The default is ``None`` for no |
| or ``None`` for no encoding. ``SHORTEST`` is only valid for |
| encoding. |
| *header_enc*. The default is ``None`` for no encoding. |
| |
| Optional *output_charset* is the character set that the output should be in. |
| Conversions will proceed from input charset, to Unicode, to the output charset |
| when the method :meth:`Charset.convert` is called. The default is to output in |
| the same character set as the input. |
| |
| Both *input_charset* and *output_charset* must have Unicode codec entries in the |
| module's character set-to-codec mapping; use :func:`add_codec` to add codecs the |