# -*- test-case-name: twisted.web.test.test_http_headers # Copyright (c) Twisted Matrix Laboratories. # See LICENSE for details. """ An API for storing HTTP header names and values. """ from __future__ import division, absolute_import from collections import MutableMapping from twisted.python.compat import comparable, cmp def _dashCapitalize(name): """ Return a byte string which is capitalized using '-' as a word separator. @param name: The name of the header to capitalize. @type name: C{bytes} @return: The given header capitalized using '-' as a word separator. @rtype: C{bytes} """ return b'-'.join([word.capitalize() for word in name.split(b'-')]) class _DictHeaders(MutableMapping): """ A C{dict}-like wrapper around L{Headers} to provide backwards compatibility for L{twisted.web.http.Request.received_headers} and L{twisted.web.http.Request.headers} which used to be plain C{dict} instances. @type _headers: L{Headers} @ivar _headers: The real header storage object. """ def __init__(self, headers): self._headers = headers def __getitem__(self, key): """ Return the last value for header of C{key}. """ if self._headers.hasHeader(key): return self._headers.getRawHeaders(key)[-1] raise KeyError(key) def __setitem__(self, key, value): """ Set the given header. """ self._headers.setRawHeaders(key, [value]) def __delitem__(self, key): """ Delete the given header. """ if self._headers.hasHeader(key): self._headers.removeHeader(key) else: raise KeyError(key) def __iter__(self): """ Return an iterator of the lowercase name of each header present. """ for k, v in self._headers.getAllRawHeaders(): yield k.lower() def __len__(self): """ Return the number of distinct headers present. """ # XXX Too many _ return len(self._headers._rawHeaders) # Extra methods that MutableMapping doesn't care about but that we do. def copy(self): """ Return a C{dict} mapping each header name to the last corresponding header value. """ return dict(self.items()) def has_key(self, key): """ Return C{True} if C{key} is a header in this collection, C{False} otherwise. """ return key in self @comparable class Headers(object): """ This class stores the HTTP headers as both a parsed representation and the raw string representation. It converts between the two on demand. @cvar _caseMappings: A C{dict} that maps lowercase header names to their canonicalized representation. @ivar _rawHeaders: A C{dict} mapping header names as C{bytes} to C{lists} of header values as C{bytes}. """ _caseMappings = { b'content-md5': b'Content-MD5', b'dnt': b'DNT', b'etag': b'ETag', b'p3p': b'P3P', b'te': b'TE', b'www-authenticate': b'WWW-Authenticate', b'x-xss-protection': b'X-XSS-Protection'} def __init__(self, rawHeaders=None): self._rawHeaders = {} if rawHeaders is not None: for name, values in rawHeaders.items(): self.setRawHeaders(name, values[:]) def __repr__(self): """ Return a string fully describing the headers set on this object. """ return '%s(%r)' % (self.__class__.__name__, self._rawHeaders,) def __cmp__(self, other): """ Define L{Headers} instances as being equal to each other if they have the same raw headers. """ if isinstance(other, Headers): return cmp( sorted(self._rawHeaders.items()), sorted(other._rawHeaders.items())) return NotImplemented def copy(self): """ Return a copy of itself with the same headers set. """ return self.__class__(self._rawHeaders) def hasHeader(self, name): """ Check for the existence of a given header. @type name: C{bytes} @param name: The name of the HTTP header to check for. @rtype: C{bool} @return: C{True} if the header exists, otherwise C{False}. """ return name.lower() in self._rawHeaders def removeHeader(self, name): """ Remove the named header from this header object. @type name: C{bytes} @param name: The name of the HTTP header to remove. @return: C{None} """ self._rawHeaders.pop(name.lower(), None) def setRawHeaders(self, name, values): """ Sets the raw representation of the given header. @type name: C{bytes} @param name: The name of the HTTP header to set the values for. @type values: C{list} @param values: A list of strings each one being a header value of the given name. @return: C{None} """ if not isinstance(values, list): raise TypeError("Header entry %r should be list but found " "instance of %r instead" % (name, type(values))) self._rawHeaders[name.lower()] = values def addRawHeader(self, name, value): """ Add a new raw value for the given header. @type name: C{bytes} @param name: The name of the header for which to set the value. @type value: C{bytes} @param value: The value to set for the named header. """ values = self.getRawHeaders(name) if values is None: self.setRawHeaders(name, [value]) else: values.append(value) def getRawHeaders(self, name, default=None): """ Returns a list of headers matching the given name as the raw string given. @type name: C{bytes} @param name: The name of the HTTP header to get the values of. @param default: The value to return if no header with the given C{name} exists. @rtype: C{list} @return: A C{list} of values for the given header. """ return self._rawHeaders.get(name.lower(), default) def getAllRawHeaders(self): """ Return an iterator of key, value pairs of all headers contained in this object, as strings. The keys are capitalized in canonical capitalization. """ for k, v in self._rawHeaders.items(): yield self._canonicalNameCaps(k), v def _canonicalNameCaps(self, name): """ Return the canonical name for the given header. @type name: C{bytes} @param name: The all-lowercase header name to capitalize in its canonical form. @rtype: C{bytes} @return: The canonical name of the header. """ return self._caseMappings.get(name, _dashCapitalize(name)) __all__ = ['Headers']