summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorR. David Murray <rdmurray@bitdance.com>2010-12-13 23:57:01 (GMT)
committerR. David Murray <rdmurray@bitdance.com>2010-12-13 23:57:01 (GMT)
commitccb9d05b6c6b32ac9429f90cf24a1da477fde79e (patch)
treea8ca264f47d0a9a985968c5397389315bd444c57 /Doc
parentfa66d583f6eb79c95ff07a84cbae1d44c81f5b8e (diff)
downloadcpython-ccb9d05b6c6b32ac9429f90cf24a1da477fde79e.zip
cpython-ccb9d05b6c6b32ac9429f90cf24a1da477fde79e.tar.gz
cpython-ccb9d05b6c6b32ac9429f90cf24a1da477fde79e.tar.bz2
Merged revisions 87217 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r87217 | r.david.murray | 2010-12-13 18:51:19 -0500 (Mon, 13 Dec 2010) | 5 lines #1078919: make add_header automatically do RFC2231 encoding when needed. Also document the use of three-tuples if control of the charset and language is desired. ........
Diffstat (limited to 'Doc')
-rw-r--r--Doc/library/email.message.rst21
1 files changed, 19 insertions, 2 deletions
diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst
index 9dcb2b4..cf02531 100644
--- a/Doc/library/email.message.rst
+++ b/Doc/library/email.message.rst
@@ -257,7 +257,15 @@ Here are the methods of the :class:`Message` class:
taken as the parameter name, with underscores converted to dashes (since
dashes are illegal in Python identifiers). Normally, the parameter will
be added as ``key="value"`` unless the value is ``None``, in which case
- only the key will be added.
+ only the key will be added. If the value contains non-ASCII characters,
+ it can be specified as a three tuple in the format
+ ``(CHARSET, LANGUAGE, VALUE)``, where ``CHARSET`` is a string naming the
+ charset to be used to encode the value, ``LANGUAGE`` can usually be set
+ to ``None`` or the empty string (see :RFC:`2231` for other possibilities),
+ and ``VALUE`` is the string value containing non-ASCII code points. If
+ a three tuple is not passed and the value contains non-ASCII characters,
+ it is automatically encoded in :RFC`2231` format using a ``CHARSET``
+ of ``utf-8`` and a ``LANGUAGE`` of ``None``.
Here's an example::
@@ -267,6 +275,15 @@ Here are the methods of the :class:`Message` class:
Content-Disposition: attachment; filename="bud.gif"
+ An example with with non-ASCII characters::
+
+ msg.add_header('Content-Disposition', 'attachment',
+ filename=('iso-8859-1', '', 'Fußballer.ppt'))
+
+ Which produces ::
+
+ Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt"
+
.. method:: replace_header(_name, _value)
@@ -356,7 +373,7 @@ Here are the methods of the :class:`Message` class:
:rfc:`2231`, you can collapse the parameter value by calling
:func:`email.utils.collapse_rfc2231_value`, passing in the return value
from :meth:`get_param`. This will return a suitably decoded Unicode
- string whn the value is a tuple, or the original string unquoted if it
+ string when the value is a tuple, or the original string unquoted if it
isn't. For example::
rawparam = msg.get_param('foo')