email.utils: raise TypeError for non-string non-3-tuple, update docs

Revised per reviewer feedback: instead of silently handling non-3-tuples,
raise TypeError with a clear message. Updated docs to say 'not a 3-tuple'
instead of 'not a tuple' to match the code's actual check.

Author: stefanzetzsche

Doc/library/email.utils.rst

@@ -212,7 +212,7 @@ of the new API.
    :rfc:`2231` header is not known by Python; it defaults to ``'us-ascii'``.
 
    For convenience, if the *value* passed to :func:`collapse_rfc2231_value` is not
-   a tuple, it should be a string and it is returned unquoted.
+   a 3-tuple, it should be a string and it is returned unquoted.
 
 
 .. function:: decode_params(params)

Lib/email/utils.py

@@ -449,8 +449,10 @@ def decode_params(params):
 def collapse_rfc2231_value(value, errors='replace',
                            fallback_charset='us-ascii'):
     if not isinstance(value, tuple) or len(value) != 3:
-        if isinstance(value, tuple):
-            return str(value)
+        if not isinstance(value, str):
+            raise TypeError(
+                f"expected str or 3-tuple, got {type(value).__name__}"
+            )
         return unquote(value)
     # While value comes to us as a unicode string, we need it to be a bytes
     # object.  We do not want bytes() normal utf-8 decoder, we want a straight

Lib/test/test_email/test_email.py

@@ -5790,14 +5790,13 @@ def test_should_not_hang_on_invalid_ew_messages(self):
                 msg = email.message_from_string(m)
 
     def test_collapse_rfc2231_value_non_3_tuple(self):
-        # collapse_rfc2231_value should not crash on tuples
-        # whose length is not 3.
+        # collapse_rfc2231_value raises TypeError on values that are
+        # neither a string nor a 3-tuple.
         from email.utils import collapse_rfc2231_value
-        # Non-3-tuples should return a string, not raise AttributeError.
-        for val in [(), ('a',), ('a', 'b'), ('a', 'b', 'c', 'd')]:
+        for val in [(), ('a',), ('a', 'b'), ('a', 'b', 'c', 'd'), 42, None]:
             with self.subTest(val=val):
-                result = collapse_rfc2231_value(val)
-                self.assertIsInstance(result, str)
+                with self.assertRaises(TypeError):
+                    collapse_rfc2231_value(val)
         # A proper 3-tuple decodes correctly.
         result = collapse_rfc2231_value(('us-ascii', 'en', 'hello'))
         self.assertEqual(result, 'hello')