Update docs, docstrings

Author: tomchristie

docs/source/api.rst

@@ -128,6 +128,21 @@ have a newline inside a header value, and ``Content-Length: hello`` is
 an error because `Content-Length` should always be an integer. We may
 add additional checks in the future.
 
+While we make sure to expose header names as lowercased bytes, we also
+preserve the original header casing that is used. Compliant HTTP
+agents should always treat headers in a case insensitive manner, but
+this may not always be the case. When sending bytes over the wire we
+use send headers preserving whatever original header casing is used.
+
+It is possible to access the headers in their raw original casing,
+which may be useful for some user output or debugging purposes.
+
+.. ipython:: python
+
+    original_headers = [("Host", "example.com")]
+    req = h11.Request(method="GET", target="/", headers=original_headers)
+    req.headers.raw_items()
+
 .. _http_version-format:
 
 It's not just headers we normalize to being byte-strings: the same

h11/_headers.py

@@ -103,6 +103,13 @@ def __eq__(self, other):
     def __len__(self):
         return len(self._full_items)
 
+    def __repr__(self):
+        return "<Headers(%s)>" % repr(list(self))
+
+    def __getitem__(self, idx):
+         _, name, value = self._full_items[idx]
+         return (name, value)
+
     def raw_items(self):
         return [(raw_name, value) for raw_name, _, value in self._full_items]
 

h11/tests/test_events.py

@@ -173,6 +173,7 @@ def test_header_casing():
         http_version="1.1",
     )
     assert len(r.headers) == 2
+    assert r.headers[0] == (b"host", b"example.org")
     assert r.headers == [(b"host", b"example.org"), (b"connection", b"keep-alive")]
     assert r.headers.raw_items() == [
         (b"Host", b"example.org"),