werkzeug.datastructures.Headers

class documentation

class Headers:

Known subclasses: werkzeug.datastructures.EnvironHeaders

An object that stores some headers. It has a dict-like interface, but is ordered, can store the same key multiple times, and iterating yields (key, value) pairs instead of only keys.

This data structure is useful if you want a nicer way to handle WSGI headers which are stored as tuples in a list.

From Werkzeug 0.3 onwards, the KeyError raised by this class is also a subclass of the ~exceptions.BadRequest HTTP exception and will render a page for a 400 BAD REQUEST if caught in a catch-all for HTTP exceptions.

Headers is mostly compatible with the Python wsgiref.headers.Headers class, with the exception of __getitem__. wsgiref will return None for headers['missing'], whereas Headers will raise a KeyError.

To create a new Headers object pass it a list or dict of headers which are used as default values. This does not reuse the list passed to the constructor for internal usage.

Changed in version 0.9: This data structure now stores unicode values similar to how the multi dicts do it. The main difference is that bytes can be set as well which will automatically be latin1 decoded.

Changed in version 0.9: The linked function was removed without replacement as it was an API that does not support the changes to the encoding model.

Parameters
defaults	The list of default values for the `Headers`.

Method	`__contains__`	Check if a key is present.
Method	`__copy__`	Undocumented
Method	`__delitem__`	Undocumented
Method	`__eq__`	Undocumented
Method	`__getitem__`	Undocumented
Method	`__init__`	Undocumented
Method	`__iter__`	Yield `(key, value)` tuples.
Method	`__len__`	Undocumented
Method	`__repr__`	Undocumented
Method	`__setitem__`	Like `set` but also supports index/slice based setting.
Method	`__str__`	Returns formatted headers suitable for HTTP transmission.
Method	`add`	Add a new header tuple to the list.
Method	`add_header`	Add a new header tuple to the list.
Method	`clear`	Clears all headers.
Method	`copy`	Undocumented
Method	`extend`	Extend headers in this object with items from another object containing header items as well as keyword arguments.
Method	`get`	No summary
Method	`get_all`	Return a list of all the values for the named field.
Method	`getlist`	No summary
Method	`has_key`	Deprecated since version 2.0: Will be removed in Werkzeug 2.1. Use `key in data` instead.
Method	`items`	Undocumented
Method	`keys`	Undocumented
Method	`pop`	Removes and returns a key or index.
Method	`popitem`	Removes a key or index and returns a (key, value) item.
Method	`remove`	Remove a key.
Method	`set`	Remove all header tuples for `key` and add a new one. The newly added key either appears at the end of the list if there was no entry or replaces the first one.
Method	`setdefault`	Return the first value for the key if it is in the headers, otherwise set the header to the value given by `default` and return that.
Method	`setlist`	Remove any existing values for a header and add new ones.
Method	`setlistdefault`	Return the list of values for the key if it is in the headers, otherwise set the header to the list of values given by `default` and return that.
Method	`to_wsgi_list`	Convert the headers into a list suitable for WSGI.
Method	`update`	Replace headers in this object with items from another headers object and keyword arguments.
Method	`values`	Undocumented
Class Variable	`__hash__`	Undocumented
Method	`_validate_value`	Undocumented
Instance Variable	`_list`	Undocumented

def __contains__(self, key):

Check if a key is present.

def __copy__(self):

Undocumented

def __delitem__(self, key, _index_operation=True):

Undocumented

def __eq__(self, other):

overridden in werkzeug.datastructures.EnvironHeaders

Undocumented

def __getitem__(self, key, _get_mode=False):

overridden in werkzeug.datastructures.EnvironHeaders

Undocumented

def __init__(self, defaults=None):

overridden in werkzeug.datastructures.EnvironHeaders

Undocumented

def __iter__(self):

overridden in werkzeug.datastructures.EnvironHeaders

Yield (key, value) tuples.

def __len__(self):

overridden in werkzeug.datastructures.EnvironHeaders

Undocumented

def __repr__(self):

Undocumented

def __setitem__(self, key, value):

Like set but also supports index/slice based setting.

def __str__(self):

Returns formatted headers suitable for HTTP transmission.

def add(self, _key, _value, **kw):

Add a new header tuple to the list.

Keyword arguments can specify additional parameters for the header value, with underscores converted to dashes:

>>> d = Headers()
>>> d.add('Content-Type', 'text/plain')
>>> d.add('Content-Disposition', 'attachment', filename='foo.png')

The keyword argument dumping uses dump_options_header behind the scenes.

New in version 0.4.1: keyword arguments were added for wsgiref compatibility.

def add_header(self, _key, _value, **_kw):

Add a new header tuple to the list.

An alias for add for compatibility with the wsgiref ~wsgiref.headers.Headers.add_header method.

def clear(self):

Clears all headers.

def copy(self):

overridden in werkzeug.datastructures.EnvironHeaders

Undocumented

def extend(self, *args, **kwargs):

Extend headers in this object with items from another object containing header items as well as keyword arguments.

To replace existing keys instead of extending, use update instead.

If provided, the first argument can be another Headers object, a MultiDict, dict, or iterable of pairs.

Changed in version 1.0: Support MultiDict. Allow passing kwargs.

def get(self, key, default=None, type=None, as_bytes=False):

Return the default value if the requested data doesn't exist. If type is provided and is a callable it should convert the value, return it or raise a ValueError if that is not possible. In this case the function will return the default as if the value was not found:

>>> d = Headers([('Content-Length', '42')])
>>> d.get('Content-Length', type=int)
42

New in version 0.9: Added support for as_bytes.

Parameters
key	The key to be looked up.
default	The default value to be returned if the key can't be looked up. If not further specified `None` is returned.
type	A callable that is used to cast the value in the `Headers`. If a `ValueError` is raised by this callable the default value is returned.
as_bytes	return bytes instead of strings.

def get_all(self, name):

Return a list of all the values for the named field.

This method is compatible with the wsgiref ~wsgiref.headers.Headers.get_all method.

def getlist(self, key, type=None, as_bytes=False):

Return the list of items for a given key. If that key is not in the Headers, the return value will be an empty list. Just like get, getlist accepts a type parameter. All items will be converted with the callable defined there.

New in version 0.9: Added support for as_bytes.

Parameters
key	The key to be looked up.
type	A callable that is used to cast the value in the `Headers`. If a `ValueError` is raised by this callable the value will be removed from the list.
as_bytes	return bytes instead of strings.
Returns
a `list` of all the values for the key.

def has_key(self, key):

Deprecated since version 2.0: Will be removed in Werkzeug 2.1. Use key in data instead.

def items(self, lower=False):

Undocumented

def keys(self, lower=False):

Undocumented

def pop(self, key=None, default=_missing):

Removes and returns a key or index.

Parameters
key	The key to be popped. If this is an integer the item at that position is removed, if it's a string the value for that key is. If the key is omitted or `None` the last item is removed.
default	Undocumented
Returns
an item.

def popitem(self):

Removes a key or index and returns a (key, value) item.

def remove(self, key):

Remove a key.

Parameters
key	The key to be removed.

def set(self, _key, _value, **kw):

Remove all header tuples for key and add a new one. The newly added key either appears at the end of the list if there was no entry or replaces the first one.

Keyword arguments can specify additional parameters for the header value, with underscores converted to dashes. See add for more information.

Changed in version 0.6.1: set now accepts the same arguments as add.

Parameters
_key	Undocumented
_value	Undocumented
**kw	Undocumented
key	The key to be inserted.
value	The value to be inserted.

def setdefault(self, key, default):

Return the first value for the key if it is in the headers, otherwise set the header to the value given by default and return that.

Parameters
key	The header key to get.
default	The value to set for the key if it is not in the headers.

def setlist(self, key, values):

Remove any existing values for a header and add new ones.

New in version 1.0.

Parameters
key	The header key to set.
values	An iterable of values to set for the key.

def setlistdefault(self, key, default):

Return the list of values for the key if it is in the headers, otherwise set the header to the list of values given by default and return that.

Unlike MultiDict.setlistdefault, modifying the returned list will not affect the headers.

New in version 1.0.

Parameters
key	The header key to get.
default	An iterable of values to set for the key if it is not in the headers.

def to_wsgi_list(self):

Convert the headers into a list suitable for WSGI.

Returns
list

def update(self, *args, **kwargs):

Replace headers in this object with items from another headers object and keyword arguments.

To extend existing keys instead of replacing, use extend instead.

If provided, the first argument can be another Headers object, a MultiDict, dict, or iterable of pairs.

New in version 1.0.

def values(self):

Undocumented

__hash__ =

overridden in werkzeug.datastructures.EnvironHeaders

Undocumented

def _validate_value(self, value):

Undocumented

_list: list =

Undocumented