Response header delete (#1032)

* added Response.delete_header()

* feat(Response): add Response.delete_header()

Previously, `Response` had methods to get and set headers, but no way to
delete them, once set. We came across a need to delete response headers
that had been set upstream, and without a `delete_header` method we've
had to resort to directly manipulating `Response._headers`. This PR
alleviates that abstraction-violation.

falcon/response.py

@@ -384,6 +384,20 @@ class Response(object):
         # NOTE(kgriffs): normalize name by lowercasing it
         self._headers[name.lower()] = value
 
+    def delete_header(self, name):
+        """Delete a header for this response.
+
+        If the header was not previously set, do nothing.
+
+        Args:
+            name (str): Header name (case-insensitive).  Must be of type
+                ``str`` or ``StringType`` and contain only US-ASCII characters.
+                Under Python 2.x, the ``unicode`` type is also accepted,
+                although such strings are also limited to US-ASCII.
+        """
+        # NOTE(kgriffs): normalize name by lowercasing it
+        self._headers.pop(name.lower(), None)
+
     def append_header(self, name, value):
         """Set or append a header for this response.
 

tests/test_headers.py

@@ -52,6 +52,12 @@ class HeaderHelpersResource(object):
 
         resp.accept_ranges = 'bytes'
 
+        # Test the removal of headers
+        resp.set_header('X-Client-Should-Never-See-This', 'abc')
+        # Confirm that the header was set
+        assert resp.get_header('x-client-should-never-see-this') == 'abc'
+        resp.delete_header('x-client-should-never-see-this')
+
         self.resp = resp
 
     def on_head(self, req, resp):
@@ -397,6 +403,9 @@ class TestHeaders(testing.TestCase):
                 hist[name] += 1
                 self.assertEqual(hist[name], 1)
 
+            # Ensure that deleted headers were not sent
+            self.assertEqual(resource.resp.get_header('x-client-should-never-see-this'), None)
+
     def test_response_append_header(self):
         self.api.add_route('/', AppendHeaderResource())