def get_header(self, name, default=None):
"""Retrieve the raw string value for the given header.
Normally, when a header has multiple values, they will be
returned as a single, comma-delimited string. However, the
Set-Cookie header does not support this format, and so
attempting to retrieve it will raise an error.
Args:
name (str): Header name, case-insensitive. Must be of type ``str``
or ``StringType``, and only character values 0x00 through 0xFF
may be used on platforms that use wide characters.
Keyword Args:
default: Value to return if the header
is not found (default ``None``).
Raises:
ValueError: The value of the 'Set-Cookie' header(s) was requested.
Returns:
str: The value of the specified header if set, or
the default value if not set.
"""
# NOTE(kgriffs): normalize name by lowercasing it
name = name.lower()
if name == 'set-cookie':
raise HeaderNotSupported(
'Getting Set-Cookie is not currently supported.')
return self._headers.get(name, default)
def delete_header(self, name):
"""Delete a header that was previously set for this response.
If the header was not previously set, nothing is done (no error is
raised). Otherwise, all values set for the header will be removed
from the response.
Note that calling this method is equivalent to setting the
corresponding header property (when said property is available) to
``None``. For example::
resp.etag = None
Warning:
This method cannot be used with the Set-Cookie header. Instead,
use :meth:`~.unset_cookie` to remove a cookie and ensure that the
user agent expires its own copy of the data as well.
Args:
name (str): Header name (case-insensitive). The name may
contain only US-ASCII characters.
Raises:
ValueError: `name` cannot be ``'Set-Cookie'``.
"""
# NOTE(kgriffs): normalize name by lowercasing it
name = name.lower()
if name == 'set-cookie':
raise HeaderNotSupported('This method cannot be used to remove cookies')
self._headers.pop(name, None)
def set_header(self, name, value):
"""Set a header for this response to a given value.
Warning:
Calling this method overwrites any values already set for this
header. To append an additional value for this header, use
:meth:`~.append_header` instead.
Warning:
This method cannot be used to set cookies; instead, use
:meth:`~.append_header` or :meth:`~.set_cookie`.
Args:
name (str): Header name (case-insensitive). The name may contain
only US-ASCII characters.
value (str): Value for the header. As with the header's name, the
value may contain only US-ASCII characters.
Raises:
ValueError: `name` cannot be ``'Set-Cookie'``.
"""
# NOTE(kgriffs): uwsgi fails with a TypeError if any header
# is not a str, so do the conversion here. It's actually
# faster to not do an isinstance check. str() will encode
# to US-ASCII.
value = str(value)
# NOTE(kgriffs): normalize name by lowercasing it
name = name.lower()
if name == 'set-cookie':
raise HeaderNotSupported('This method cannot be used to set cookies')
self._headers[name] = value
def set_headers(self, headers):
"""Set several headers at once.
This method can be used to set a collection of raw header names and
values all at once.
Warning:
Calling this method overwrites any existing values for the given
header. If a list containing multiple instances of the same header
is provided, only the last value will be used. To add multiple
values to the response for a given header, see
:meth:`~.append_header`.
Warning:
This method cannot be used to set cookies; instead, use
:meth:`~.append_header` or :meth:`~.set_cookie`.
Args:
headers (dict or list): A dictionary of header names and values
to set, or a ``list`` of (*name*, *value*) tuples. Both *name*
and *value* 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:
Falcon can process a list of tuples slightly faster
than a dict.
Raises:
ValueError: `headers` was not a ``dict`` or ``list`` of ``tuple``.
"""
if isinstance(headers, dict):
headers = headers.items()
# NOTE(kgriffs): We can't use dict.update because we have to
# normalize the header names.
_headers = self._headers
for name, value in headers:
# NOTE(kgriffs): uwsgi fails with a TypeError if any header
# is not a str, so do the conversion here. It's actually
# faster to not do an isinstance check. str() will encode
# to US-ASCII.
name = str(name)
value = str(value)
name = name.lower()
if name == 'set-cookie':
raise HeaderNotSupported(
'This method cannot be used to set cookies')
_headers[name] = value
def set_headers(self, headers):
"""Set several headers at once.
This method can be used to set a collection of raw header names and
values all at once.
Warning:
Calling this method overwrites any existing values for the given
header. If a list containing multiple instances of the same header
is provided, only the last value will be used. To add multiple
values to the response for a given header, see
:meth:`~.append_header`.
Warning:
This method cannot be used to set cookies; instead, use
:meth:`~.append_header` or :meth:`~.set_cookie`.
Args:
headers (Iterable[[str, str]]): An iterable of ``[name, value]`` two-member
iterables, or a dict-like object that implements an ``items()`` method.
Both *name* and *value* must be of type ``str`` and
contain only US-ASCII characters.
Note:
Falcon can process an iterable of tuples slightly faster
than a dict.
Raises:
ValueError: `headers` was not a ``dict`` or ``list`` of ``tuple``
or ``Iterable[[str, str]]``.
"""
header_items = getattr(headers, 'items', None)
if callable(header_items):
headers = header_items()
# NOTE(kgriffs): We can't use dict.update because we have to
# normalize the header names.
_headers = self._headers
for name, value in headers:
# NOTE(kgriffs): uwsgi fails with a TypeError if any header
# is not a str, so do the conversion here. It's actually
# faster to not do an isinstance check. str() will encode
# to US-ASCII.
value = str(value)
name = name.lower()
if name == 'set-cookie':
raise HeaderNotSupported(
'This method cannot be used to set cookies')
_headers[name] = value
def set_header(self, name, value):
"""Set a header for this response to a given value.
Warning:
Calling this method overwrites any values already set for this
header. To append an additional value for this header, use
:meth:`~.append_header` instead.
Warning:
This method cannot be used to set cookies; instead, use
:meth:`~.append_header` or :meth:`~.set_cookie`.
Args:
name (str): Header name (case-insensitive). The restrictions
noted below for the header's value also apply here.
value (str): Value for the header. Must be convertable to
``str`` or be of type ``str`` or
``StringType``. Strings must contain only US-ASCII characters.
Under Python 2.x, the ``unicode`` type is also accepted,
although such strings are also limited to US-ASCII.
Raises:
ValueError: `name` cannot be ``'Set-Cookie'``.
"""
# NOTE(kgriffs): uwsgi fails with a TypeError if any header
# is not a str, so do the conversion here. It's actually
# faster to not do an isinstance check. str() will encode
# to US-ASCII.
name = str(name)
value = str(value)
# NOTE(kgriffs): normalize name by lowercasing it
name = name.lower()
if name == 'set-cookie':
raise HeaderNotSupported(
'This method cannot be used to set cookies')
self._headers[name] = value
