#1078919: document requirement to use triples for non-ascii add_header parms.

diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst
index fa1df8888fe49b4d6451f79ff5e44b17ce058907..6f40c05ef4c2191f791fcc8b692be0aad7ee810c 100644 (file)
--- a/Doc/library/email.message.rst
+++ b/Doc/library/email.message.rst
@@ -266,7 +266,12 @@ 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 must 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.
 
       Here's an example::
 
@@ -276,6 +281,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)
 
@@ -380,7 +394,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')

diff --git a/Lib/email/message.py b/Lib/email/message.py
index 40f808e8b5330072db34a61ab898b300e3e60e87..7c93370984c0d040dde803bd88101c2bbde0d1ea 100644 (file)
--- a/Lib/email/message.py
+++ b/Lib/email/message.py
@@ -38,7 +38,9 @@ def _splitparam(param):
 def _formatparam(param, value=None, quote=True):
     """Convenience function to format and return a key=value pair.
 
-    This will quote the value if needed or if quote is true.
+    This will quote the value if needed or if quote is true.  If value is a
+    three tuple (charset, language, value), it will be encoded according
+    to RFC2231 rules.
     """
     if value is not None and len(value) > 0:
         # A tuple is used for RFC 2231 encoded parameter values where items
@@ -389,7 +391,10 @@ class Message:
         name is the header field to add.  keyword arguments can be used to set
         additional parameters for the header field, with underscores converted
         to dashes.  Normally the parameter will be added as key="value" unless
-        value is None, in which case only the key will be added.
+        value is None, in which case only the key will be added.  If a
+        parameter value contains non-ASCII characters it must be specified as a
+        three-tuple of (charset, language, value), in which case it will be
+        encoded according to RFC2231 rules.
 
         Example:
 

diff --git a/Lib/email/test/test_email.py b/Lib/email/test/test_email.py
index d93287a474e17f630f94550168ea7e29eca58947..7a1d699cf62a8a9b21037ddcb5103f70f7d87726 100644 (file)
--- a/Lib/email/test/test_email.py
+++ b/Lib/email/test/test_email.py
@@ -3113,6 +3113,21 @@ A very long line that must get split to something other than at the
         s = 'Subject: =?EUC-KR?B?CSixpLDtKSC/7Liuvsax4iC6uLmwMcijIKHaILzSwd/H0SC8+LCjwLsgv7W/+Mj3I ?='
         raises(Errors.HeaderParseError, decode_header, s)
 
+    # Issue 1078919
+    def test_ascii_add_header(self):
+        msg = Message()
+        msg.add_header('Content-Disposition', 'attachment',
+                       filename='bud.gif')
+        self.assertEqual('attachment; filename="bud.gif"',
+            msg['Content-Disposition'])
+
+    def test_nonascii_add_header_via_triple(self):
+        msg = Message()
+        msg.add_header('Content-Disposition', 'attachment',
+            filename=('iso-8859-1', '', 'Fu\xdfballer.ppt'))
+        self.assertEqual(
+            'attachment; filename*="iso-8859-1\'\'Fu%DFballer.ppt"',
+            msg['Content-Disposition'])
 
 
 # Test RFC 2231 header parameters (en/de)coding