Clean up public API for Headers data structure

Author: lovelydinosaur

h11/_headers.py

@@ -63,21 +63,49 @@
 
 
 class Headers:
-    __slots__ = ['raw_items']
-
-    def __init__(self, raw_items):
-        self.raw_items = raw_items
+    """
+    A list-like interface that allows iterating over headers as byte-pairs
+    of (lowercased-name, value).
+
+    Internally we actually store the representation as three-tuples,
+    including both the raw original casing, in order to preserve casing
+    over-the-wire, and the lowercased name, for case-insensitive comparisions.
+
+    r = Request(
+        method="GET",
+        target="/",
+        headers=[("Host", "example.org"), ("Connection", "keep-alive")],
+        http_version="1.1",
+    )
+    assert r.headers == [
+        (b"host", b"example.org"),
+        (b"connection", b"keep-alive")
+    ]
+    assert r.headers.raw_items() == [
+        (b"Host", b"example.org"),
+        (b"Connection", b"keep-alive")
+    ]
+    """
+
+    def __init__(self, full_items):
+        self._full_items = full_items
 
     def __iter__(self):
-        for _, name, value in self.raw_items:
+        for _, name, value in self._full_items:
             yield name, value
 
     def __bool__(self):
-        return bool(self.raw_items)
+        return bool(self._full_items)
 
     def __eq__(self, other):
         return list(self) == list(other)
 
+    def __len__(self):
+        return len(self._full_items)
+
+    def raw_items(self):
+        return [(raw_name, value) for raw_name, _, value in self._full_items]
+
 
 def normalize_and_validate(headers, _parsed=False):
     new_headers = []
@@ -158,7 +186,7 @@ def get_comma_header(headers, name):
     # "100-continue". Splitting on commas is harmless. Case insensitive.
     #
     out = []
-    for _, found_name, found_raw_value in headers.raw_items:
+    for _, found_name, found_raw_value in headers._full_items:
         if found_name == name:
             found_raw_value = found_raw_value.lower()
             for found_split_value in found_raw_value.split(b","):
@@ -171,7 +199,7 @@ def get_comma_header(headers, name):
 def set_comma_header(headers, name, new_values):
     # The header name `name` is expected to be lower-case bytes.
     new_headers = []
-    for found_raw_name, found_name, found_raw_value in headers.raw_items:
+    for found_raw_name, found_name, found_raw_value in headers._full_items:
         if found_name != name:
             new_headers.append((found_raw_name, found_raw_value))
     for new_value in new_values:

h11/_writers.py

@@ -38,7 +38,7 @@ def write_headers(headers, write):
     # "Since the Host field-value is critical information for handling a
     # request, a user agent SHOULD generate Host as the first header field
     # following the request-line." - RFC 7230
-    raw_items = headers.raw_items
+    raw_items = headers._full_items
     for raw_name, name, value in raw_items:
         if name == b"host":
             write(bytesmod(b"%s: %s\r\n", (raw_name, value)))

h11/tests/test_events.py

@@ -163,3 +163,15 @@ def test_intenum_status_code():
     assert r.status_code == HTTPStatus.OK
     assert type(r.status_code) is not type(HTTPStatus.OK)
     assert type(r.status_code) is int
+
+
+def test_header_casing():
+    r = Request(
+        method="GET",
+        target="/",
+        headers=[("Host", "example.org"), ("Connection", "keep-alive")],
+        http_version="1.1",
+    )
+    assert len(r.headers) == 2
+    assert r.headers == [(b"host", b"example.org"), (b"connection", b"keep-alive")]
+    assert r.headers.raw_items() == [(b"Host", b"example.org"), (b"Connection", b"keep-alive")]