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