Initial header set implementation.

Author: Lukasa

hyper/common/__init__.py

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+"""
+hyper/common
+~~~~~~~~~~~~
+
+Common code in hyper.
+"""

hyper/common/headers.py

@@ -0,0 +1,161 @@
+# -*- coding: utf-8 -*-
+"""
+hyper/common/headers
+~~~~~~~~~~~~~~~~~~~~~
+
+Contains hyper's structures for storing and working with HTTP headers.
+"""
+import collections
+
+
+class HTTPHeaderMap(collections.MutableMapping):
+    """
+    A structure that contains HTTP headers.
+
+    HTTP headers are a curious beast. At the surface level they look roughly
+    like a name-value set, but in practice they have many variations that
+    make them tricky:
+
+    - duplicate keys are allowed
+    - keys are compared case-insensitively
+    - duplicate keys are isomorphic to comma-separated values, *except when
+      they aren't*!
+    - they logically contain a form of ordering
+
+    This data structure is an attempt to preserve all of that information
+    while being as user-friendly as possible.
+    """
+    def __init__(self, *args, **kwargs):
+        # The meat of the structure. In practice, headers are an ordered list
+        # of tuples. This early version of the data structure simply uses this
+        # directly under the covers.
+        self._items = []
+
+        for arg in args:
+            for item in arg:
+                self._items.extend(canonical_form(*item))
+
+        for k, v in kwargs.items():
+            self._items.extend(canonical_form(k, v))
+
+    def __getitem__(self, key):
+        """
+        Unlike the dict __getitem__, this returns a list of items in the order
+        they were added.
+        """
+        values = []
+
+        for k, v in self._items:
+            if _keys_equal(k, key):
+                values.append(v)
+
+        if not values:
+            raise KeyError()
+
+        return values
+
+    def __setitem__(self, key, value):
+        """
+        Unlike the dict __setitem__, this appends to the list of items. It also
+        splits out headers that can be split on the comma.
+        """
+        self._items.extend(canonical_form(key, value))
+
+    def __delitem__(self, key):
+        """
+        Sadly, __delitem__ is kind of stupid here, but the best we can do is
+        delete all headers with a given key. To correctly achieve the 'KeyError
+        on missing key' logic from dictionaries, we need to do this slowly.
+        """
+        indices = []
+        for (i, (k, v)) in enumerate(self._items):
+            if _keys_equal(k, key):
+                indices.append(i)
+
+        if not indices:
+            raise KeyError()
+
+        for i in indices[::-1]:
+            self._items.pop(i)
+
+    def __iter__(self):
+        """
+        This mapping iterates like the list of tuples it is.
+        """
+        for pair in self._items:
+            yield pair
+
+    def __len__(self):
+        """
+        The length of this mapping is the number of individual headers.
+        """
+        return len(self._items)
+
+    def __contains__(self, key):
+        """
+        If any header is present with this key, returns True.
+        """
+        return any(_keys_equal(key, k) for k, _ in self._items)
+
+    def keys(self):
+        """
+        Returns an iterable of the header keys in the mapping. This explicitly
+        does not filter duplicates, ensuring that it's the same length as
+        len().
+        """
+        for n, _ in self._items:
+            yield n
+
+    def items(self):
+        """
+        This mapping iterates like the list of tuples it is.
+        """
+        for item in self:
+            yield item
+
+    def values(self):
+        """
+        This is an almost nonsensical query on a header dictionary, but we
+        satisfy it in the exact same way we satisfy 'keys'.
+        """
+        for _, v in self._items:
+            yield v
+
+    def get(self, name, default=None):
+        """
+        Unlike the dict get, this returns a list of items in the order
+        they were added.
+        """
+        try:
+            return self[name]
+        except KeyError:
+            return default
+
+    def __eq__(self, other):
+        return self._items == other._items
+
+    def __ne__(self, other):
+        return self._items != other._items
+
+
+def canonical_form(k, v):
+    """
+    Returns an iterable of key-value-pairs corresponding to the header in
+    canonical form. This means that the header is split on commas unless for
+    any reason it's a super-special snowflake (I'm looking at you Set-Cookie).
+    """
+    SPECIAL_SNOWFLAKES = set(['set-cookie', 'set-cookie2'])
+
+    k = k.lower()
+
+    if k in SPECIAL_SNOWFLAKES:
+        yield k, v
+    else:
+        for sub_val in v.split(','):
+            yield k, sub_val.strip()
+
+def _keys_equal(x, y):
+    """
+    Returns 'True' if the two keys are equal by the laws of HTTP headers.
+    """
+    return x.lower() == y.lower()

test/test_headers.py

@@ -0,0 +1,187 @@
+from hyper.common.headers import HTTPHeaderMap
+
+import pytest
+
+class TestHTTPHeaderMap(object):
+    def test_header_map_can_insert_single_header(self):
+        h = HTTPHeaderMap()
+        h['key'] = 'value'
+        assert h['key'] == ['value']
+
+    def test_header_map_insensitive_key(self):
+        h = HTTPHeaderMap()
+        h['KEY'] = 'value'
+        assert h['key'] == ['value']
+
+    def test_header_map_is_iterable_in_order(self):
+        h = HTTPHeaderMap()
+        items = [
+            ('k1', 'v2'),
+            ('k2', 'v2'),
+            ('k2', 'v3'),
+        ]
+
+        for k, v in items:
+            h[k] = v
+
+        for i, pair in enumerate(h):
+            assert items[i] == pair
+
+    def test_header_map_allows_multiple_values(self):
+        h = HTTPHeaderMap()
+        h['key'] = 'v1'
+        h['Key'] = 'v2'
+
+        assert h['key'] == ['v1', 'v2']
+
+    def test_header_map_can_delete_value(self):
+        h = HTTPHeaderMap()
+        h['key'] = 'v1'
+        del h['key']
+
+        with pytest.raises(KeyError):
+            h['key']
+
+    def test_header_map_deletes_all_values(self):
+        h = HTTPHeaderMap()
+        h['key'] = 'v1'
+        h['key'] = 'v2'
+        del h['key']
+
+        with pytest.raises(KeyError):
+            h['key']
+
+    def test_setting_comma_separated_header(self):
+        h = HTTPHeaderMap()
+        h['key'] = 'v1, v2'
+
+        assert h['key'] == ['v1', 'v2']
+
+    def test_containment(self):
+        h = HTTPHeaderMap()
+        h['key'] = 'val'
+
+        assert 'key' in h
+        assert 'nonkey' not in h
+
+    def test_length_counts_lines_separately(self):
+        h = HTTPHeaderMap()
+        h['k1'] = 'v1, v2'
+        h['k2'] = 'v3'
+        h['k1'] = 'v4'
+
+        assert len(h) == 4
+
+    def test_keys(self):
+        h = HTTPHeaderMap()
+        h['k1'] = 'v1, v2'
+        h['k2'] = 'v3'
+        h['k1'] = 'v4'
+
+        assert len(list(h.keys())) == 4
+        assert list(h.keys()) == ['k1', 'k1', 'k2', 'k1']
+
+    def test_values(self):
+        h = HTTPHeaderMap()
+        h['k1'] = 'v1, v2'
+        h['k2'] = 'v3'
+        h['k1'] = 'v4'
+
+        assert len(list(h.values())) == 4
+        assert list(h.values()) == ['v1', 'v2', 'v3', 'v4']
+
+    def test_items(self):
+        h = HTTPHeaderMap()
+        items = [
+            ('k1', 'v2'),
+            ('k2', 'v2'),
+            ('k2', 'v3'),
+        ]
+
+        for k, v in items:
+            h[k] = v
+
+        for i, pair in enumerate(h.items()):
+            assert items[i] == pair
+
+    def test_empty_get(self):
+        h = HTTPHeaderMap()
+        assert h.get('nonexistent', 'hi there') == 'hi there'
+
+    def test_actual_get(self):
+        h = HTTPHeaderMap()
+        h['k1'] = 'v1, v2'
+        h['k2'] = 'v3'
+        h['k1'] = 'v4'
+
+        assert h.get('k1') == ['v1', 'v2', 'v4']
+
+    def test_doesnt_split_set_cookie(self):
+        h = HTTPHeaderMap()
+        h['Set-Cookie'] = 'v1, v2'
+        assert h['set-cookie'] == ['v1, v2']
+        assert h.get('set-cookie') == ['v1, v2']
+
+    def test_equality(self):
+        h1 = HTTPHeaderMap()
+        h1['k1'] = 'v1, v2'
+        h1['k2'] = 'v3'
+        h1['k1'] = 'v4'
+
+        h2 = HTTPHeaderMap()
+        h2['k1'] = 'v1'
+        h2['k1'] = 'v2'
+        h2['k2'] = 'v3'
+        h2['k1'] = 'v4'
+
+        assert h1 == h2
+
+    def test_inequality(self):
+        h1 = HTTPHeaderMap()
+        h1['k1'] = 'v1, v2'
+        h1['k2'] = 'v3'
+        h1['k1'] = 'v4'
+
+        h2 = HTTPHeaderMap()
+        h2['k1'] = 'v1'
+        h2['k1'] = 'v4'
+        h2['k1'] = 'v2'
+        h2['k2'] = 'v3'
+
+        assert h1 != h2
+
+    def test_deleting_nonexistent(self):
+        h = HTTPHeaderMap()
+
+        with pytest.raises(KeyError):
+            del h['key']
+
+    def test_can_create_from_iterable(self):
+        items = [
+            ('k1', 'v2'),
+            ('k2', 'v2'),
+            ('k2', 'v3'),
+        ]
+        h = HTTPHeaderMap(items)
+
+        assert list(h) == items
+
+    def test_can_create_from_multiple_iterables(self):
+        items = [
+            ('k1', 'v2'),
+            ('k2', 'v2'),
+            ('k2', 'v3'),
+        ]
+        h = HTTPHeaderMap(items, items, items)
+
+        assert list(h) == items + items + items
+
+    def test_create_from_iterables_and_kwargs(self):
+        items = [
+            ('k1', 'v2'),
+            ('k2', 'v2'),
+            ('k2', 'v3'),
+        ]
+        h = HTTPHeaderMap(items, k3='v4', k4='v5')
+
+        assert list(h) == items + [('k3', 'v4'), ('k4', 'v5')]