Improve error message for non-ASCII header encoding errors

When headers contain non-ASCII characters, the error message now
includes the header name to make debugging easier.

Fixes #3400

Author: suojae

httpx/_models.py

@@ -64,22 +64,68 @@ def _is_known_encoding(encoding: str) -> bool:
     return True
 
 
-def _normalize_header_key(key: str | bytes, encoding: str | None = None) -> bytes:
+def _normalize_header_key(
+    key: str | bytes,
+    encoding: str | None = None,
+    header_name: str | bytes | None = None,
+) -> bytes:
     """
     Coerce str/bytes into a strictly byte-wise HTTP header key.
     """
-    return key if isinstance(key, bytes) else key.encode(encoding or "ascii")
-
-
-def _normalize_header_value(value: str | bytes, encoding: str | None = None) -> bytes:
+    if isinstance(key, bytes):
+        return key
+    try:
+        return key.encode(encoding or "ascii")
+    except UnicodeEncodeError as exc:
+        if header_name:
+            name_str = (
+                header_name
+                if isinstance(header_name, str)
+                else header_name.decode("ascii", errors="replace")
+            )
+            header_info = f" '{name_str}'"
+        else:
+            header_info = ""
+        raise UnicodeEncodeError(
+            exc.encoding,
+            exc.object,
+            exc.start,
+            exc.end,
+            f"Header name{header_info} contains non-ASCII characters",
+        ) from exc
+
+
+def _normalize_header_value(
+    value: str | bytes,
+    encoding: str | None = None,
+    header_name: str | bytes | None = None,
+) -> bytes:
     """
     Coerce str/bytes into a strictly byte-wise HTTP header value.
     """
     if isinstance(value, bytes):
         return value
     if not isinstance(value, str):
         raise TypeError(f"Header value must be str or bytes, not {type(value)}")
-    return value.encode(encoding or "ascii")
+    try:
+        return value.encode(encoding or "ascii")
+    except UnicodeEncodeError as exc:
+        if header_name:
+            name_str = (
+                header_name
+                if isinstance(header_name, str)
+                else header_name.decode("ascii", errors="replace")
+            )
+            header_info = f" '{name_str}'"
+        else:
+            header_info = ""
+        raise UnicodeEncodeError(
+            exc.encoding,
+            exc.object,
+            exc.start,
+            exc.end,
+            f"Header{header_info} value contains non-ASCII characters",
+        ) from exc
 
 
 def _parse_content_type_charset(content_type: str) -> str | None:
@@ -152,13 +198,13 @@ def __init__(
             self._list = list(headers._list)
         elif isinstance(headers, Mapping):
             for k, v in headers.items():
-                bytes_key = _normalize_header_key(k, encoding)
-                bytes_value = _normalize_header_value(v, encoding)
+                bytes_key = _normalize_header_key(k, encoding, header_name=k)
+                bytes_value = _normalize_header_value(v, encoding, header_name=k)
                 self._list.append((bytes_key, bytes_key.lower(), bytes_value))
         elif headers is not None:
             for k, v in headers:
-                bytes_key = _normalize_header_key(k, encoding)
-                bytes_value = _normalize_header_value(v, encoding)
+                bytes_key = _normalize_header_key(k, encoding, header_name=k)
+                bytes_value = _normalize_header_value(v, encoding, header_name=k)
                 self._list.append((bytes_key, bytes_key.lower(), bytes_value))
 
         self._encoding = encoding

tests/models/test_headers.py

@@ -217,3 +217,13 @@ def test_parse_header_links(value, expected):
 def test_parse_header_links_no_link():
     all_links = httpx.Response(200).links
     assert all_links == {}
+
+
+def test_header_encoding_error_mentions_header_name():
+    with pytest.raises(UnicodeEncodeError, match="Header 'auth' value"):
+        httpx.Headers({"auth": "안녕하세요"})
+
+
+def test_header_key_encoding_error_mentions_header_name():
+    with pytest.raises(UnicodeEncodeError, match="Header name '헤더'"):
+        httpx.Headers({"헤더": "value"})