2.1. DictView class

class immutable_views.DictView(a_dict)[source]

An immutable dictionary view.

Derived from Mapping.

This class provides an immutable view on a possibly mutable mapping object. The mapping object must be an instance of Mapping, e.g. dict, or a user-defined class.

This can be used for example when a class maintains a dictionary that should be made available to users of the class without allowing them to modify the dictionary.

In the description of this class, the term ‘view’ always refers to the DictView object, and the term ‘dictionary’ or ‘underlying dictionary’ refers to the mapping object the view is based on.

The DictView class supports the complete behavior of Python class dict, except for any methods that would modify the dictionary. Note that the non-modifying methods of class dict are a superset of the methods defined for the abstract class Mapping (the methods are listed in the table at the top of the linked page).

The view is “live”: Since the view class delegates all operations to the underlying dictionary, any modification of the underlying dictionary object will be visible in the view object.

Note that only the view object is immutable, not its items. So if the values in the underlying dictionary are mutable objects, they can be modified through the view.

Note that in Python, augmented assignment (e.g. x += y) is not guaranteed to modify the left hand object in place, but can result in the left hand name being bound to a new object (like in x = x + y). For details, see object.__iadd__().

For the DictView class, augmented assignment is supported and results in binding the left hand name to a new DictView object.

Parameters

a_dict (Mapping) – The underlying dictionary. If this object is a DictView, its underlying dictionary is used.

Methods:

__contains__(key)

value in self: Return a boolean indicating whether the dictionary contains an item with a key.

__eq__(other)

self == other: Return a boolean indicating whether the dictionary is equal to the other object.

__ge__(other)

self >= other: Return a boolean indicating whether the dictionary is greater than or equal to the other dictionary.

__getitem__(key)

self[key]: Return the value of the dictionary item with a key.

__getstate__()

Support for pickling.

__gt__(other)

self > other: Return a boolean indicating whether the dictionary is greater than the other dictionary.

__hash__()

hash(self): Return a hash value for the dictionary.

__iter__()

Return an iterator through the dictionary keys in iteration order.

__le__(other)

self <= other: Return a boolean indicating whether the dictionary is less than or equal to the other dictionary.

__len__()

len(self): Return the number of items in the dictionary.

__lt__(other)

self < other: Return a boolean indicating whether the dictionary is less than the other dictionary.

__ne__(other)

self != other: Return a boolean indicating whether the dictionary is not equal to the other dictionary.

__or__(other)

self | other: Return a new view on the merged dictionary and other dictionary.

__repr__()

repr(self): Return a string representation of the view suitable for debugging.

__reversed__()

reversed(self) ...: Return an iterator through the dictionary keys in reversed iteration order.

__ror__(other)

other | self: Return a new view on the merged dictionary and other dictionary.

__setstate__(a_dict)

Support for unpickling.

copy()

Return a new view on a shallow copy of the dictionary.

get(key[, default])

Return the value of the dictionary item with a key or a default value.

has_key(key)

Python 2 only: Return a boolean indicating whether the dictionary contains an item with a key.

items()

Return the dictionary items in iteration order.

iteritems()

Python 2 only: Return an iterator through the dictionary items in iteration order.

iterkeys()

Python 2 only: Return an iterator through the dictionary keys in iteration order.

itervalues()

Python 2 only: Return an iterator through the dictionary values in iteration order.

keys()

Return the dictionary keys in iteration order.

values()

Return the dictionary values in iteration order.

viewitems()

Python 2 only: Return a view on the dictionary items in iteration order.

viewkeys()

Python 2 only: Return a view on the dictionary keys in iteration order.

viewvalues()

Python 2 only: Return a view on the dictionary values in iteration order.

Attributes:

dict

The underlying dictionary.

__contains__(key)[source]

value in self: Return a boolean indicating whether the dictionary contains an item with a key.

The return value indicates whether the underlying dictionary contains an item that has the specified key.

__eq__(other)[source]

self == other: Return a boolean indicating whether the dictionary is equal to the other object.

Compared are the underlying dictionary of the left hand view object and the right hand object (or in case of a DictView, its underlying dictionary).

__ge__(other)[source]

self >= other: Return a boolean indicating whether the dictionary is greater than or equal to the other dictionary.

Whether ordering comparison is supported and how ordering is defined depends on the underlying dictionary and the other dictionary. For example, the standard Python dict class does not support ordering comparisons on Python 3.

The other object must be a dict or DictView.

Raises
  • TypeError – The other object is not a dict or DictView.

  • TypeError – The underlying dictionary does not support ordering comparisons.

__getitem__(key)[source]

self[key]: Return the value of the dictionary item with a key.

Raises

KeyError – An item with the key does not exist.

__getstate__()[source]

Support for pickling.

__gt__(other)[source]

self > other: Return a boolean indicating whether the dictionary is greater than the other dictionary.

Whether ordering comparison is supported and how ordering is defined depends on the underlying dictionary and the other dictionary. For example, the standard Python dict class does not support ordering comparisons on Python 3.

The other object must be a dict or DictView.

Raises
  • TypeError – The other object is not a dict or DictView.

  • TypeError – The underlying dictionary does not support ordering comparisons.

__hash__()[source]

hash(self): Return a hash value for the dictionary.

Whether hashing is supported depends on the underlying dictionary. For example, the standard Python dict class does not support hashing.

Raises

TypeError – The underlying dictionary does not support hashing.

__iter__()[source]

Return an iterator through the dictionary keys in iteration order.

__le__(other)[source]

self <= other: Return a boolean indicating whether the dictionary is less than or equal to the other dictionary.

Whether ordering comparison is supported and how ordering is defined depends on the underlying dictionary and the other dictionary. For example, the standard Python dict class does not support ordering comparisons on Python 3.

The other object must be a dict or DictView.

Raises
  • TypeError – The other object is not a dict or DictView.

  • TypeError – The underlying dictionary does not support ordering comparisons.

__len__()[source]

len(self): Return the number of items in the dictionary.

The return value is the number of items in the underlying dictionary.

__lt__(other)[source]

self < other: Return a boolean indicating whether the dictionary is less than the other dictionary.

Whether ordering comparison is supported and how ordering is defined depends on the underlying dictionary and the other dictionary. For example, the standard Python dict class does not support ordering comparisons on Python 3.

The other object must be a dict or DictView.

Raises
  • TypeError – The other object is dict a set or DictView.

  • TypeError – The underlying dictionary does not support ordering comparisons.

__ne__(other)[source]

self != other: Return a boolean indicating whether the dictionary is not equal to the other dictionary.

Compared are the underlying dictionary of the left hand view object and the right hand object (or in case of a DictView, its underlying dictionary).

__or__(other)[source]

self | other: Return a new view on the merged dictionary and other dictionary.

Added in Python 3.9.

The returned DictView object is a view on a new dictionary object of the type of the left hand operand that contains all the items from the underlying dictionary of the left hand operand, updated by the items from the other dictionary (or in case of a DictView, its underlying dictionary).

The other object must be a dict or DictView.

The dictionary and the other dictionary are not changed.

Raises

TypeError – The other object is not a dict or DictView.

__repr__()[source]

repr(self): Return a string representation of the view suitable for debugging.

The underlying dictionary is represented using its repr() representation.

__reversed__()[source]

reversed(self) ...: Return an iterator through the dictionary keys in reversed iteration order.

Added in Python 3.8.

The returned iterator yields the keys in the underlying dictionary in reversed iteration order.

__ror__(other)[source]

other | self: Return a new view on the merged dictionary and other dictionary.

Added in Python 3.9.

This method is a fallback and is called only if the left operand does not support the operation.

The returned DictView object is a view on a new dictionary object of the type of the right hand operand that contains all the items from the underlying dictionary of the right hand operand, updated by the items from the other dictionary (or in case of a DictView, its underlying dictionary).

The other object must be a dict or DictView.

The dictionary and the other dictionary are not changed.

Raises

TypeError – The other object is not a dict or DictView.

__setstate__(a_dict)[source]

Support for unpickling.

copy()[source]

Return a new view on a shallow copy of the dictionary.

The returned DictView object is a new view object on a dictionary object of the type of the underlying dictionary.

If the dictionary type is immutable, the returned dictionary object may be the underlying dictionary object. If the dictionary type is mutable, the returned dictionary is a new dictionary object that is a shallow copy of the underlying dictionary object.

property dict

The underlying dictionary.

Access to the underlying dictionary is provided for purposes such as conversion to JSON or other cases where the view classes do not work. This access should not be used to modify the underlying dictionary.

get(key, default=None)[source]

Return the value of the dictionary item with a key or a default value.

has_key(key)[source]

Python 2 only: Return a boolean indicating whether the dictionary contains an item with a key.

Raises

AttributeError – The method does not exist on Python 3.

items()[source]

Return the dictionary items in iteration order.

Each returned item is a tuple of key and value. The items of the underlying dictionary are returned as a view in Python 3 and as a list in Python 2.

See Dictionary View Objects on Python 3 for details about view objects.

iteritems()[source]

Python 2 only: Return an iterator through the dictionary items in iteration order.

Each item is a tuple of key and value.

Raises

AttributeError – The method does not exist on Python 3.

iterkeys()[source]

Python 2 only: Return an iterator through the dictionary keys in iteration order.

Raises

AttributeError – The method does not exist on Python 3.

itervalues()[source]

Python 2 only: Return an iterator through the dictionary values in iteration order.

Raises

AttributeError – The method does not exist on Python 3.

keys()[source]

Return the dictionary keys in iteration order.

The keys of the underlying dictionary are returned as a view in Python 3 and as a list in Python 2.

See Dictionary View Objects on Python 3 for details about view objects.

values()[source]

Return the dictionary values in iteration order.

The values of the underlying dictionary are returned as a view in Python 3 and as a list in Python 2.

See Dictionary View Objects on Python 3 for details about view objects.

viewitems()[source]

Python 2 only: Return a view on the dictionary items in iteration order.

Each returned item is a tuple of key and value. The items of the underlying dictionary are returned as a view.

See Dictionary View Objects on Python 2 for details about view objects.

Raises

AttributeError – The method does not exist on Python 3.

viewkeys()[source]

Python 2 only: Return a view on the dictionary keys in iteration order.

The keys of the underlying dictionary are returned as a view.

See Dictionary View Objects on Python 2 for details about view objects.

Raises

AttributeError – The method does not exist on Python 3.

viewvalues()[source]

Python 2 only: Return a view on the dictionary values in iteration order.

The values of the underlying dictionary are returned as a view.

See Dictionary View Objects on Python 2 for details about view objects.

Raises

AttributeError – The method does not exist on Python 3.