immutable-views 0.5.0

Immutable views on other collection objects

Overview

The immutable-views package provides collection classes that are immutable views on other (mutable) collection objects:

• immutable_views.DictView - immutable view on another mapping object.

• immutable_views.ListView - immutable view on another list (sequence) object.

• immutable_views.SetView - immutable view on another set object.

An important behavior of views is that they are “live”: Since the view classes delegate to the original collection, any modification of the original collection object will be visible in the view object.

Creating an immutable view on a collection does not copy the collection and is therefore much faster than creating an immutable copy of the collection.

This is useful if a method or function maintains data in form of a mutable collection and is intended to return that data but users should not be able to modify the data. The original collection can be updated by the method or function as needed, but the caller only gets an immutable view on it.

The view classes in the immutable-views package implement the complete behavior of the corresponding Python collection types except for any operations that would modify the collection object.

The view classes delegate all operations to the original collection object they are a view of. Therefore, the original collection can be any kind of collection implementation (i.e. not just the original Python collection classes).

Note that the immutability of the view objects only applies to the view object itself, but not to the items shown by the view. So if the original collection contains mutable objects, they will still be mutable when accessed through the view objects. However, since string types are immutable in Python, for example the common case of a dictionary with string-typed keys and string-typed values results in complete immutability of the dictionary and its items.

Example with dictionaries:

$ python
>>> from immutable_views import DictView
>>> dict1 = {'a': 1, 'b': 2}
>>> dictview1 = DictView(dict1)

# Read-only access to the view is supported:
>>> dictview1['a']
1

# Modifying the view is rejected:
>>> dictview1['a'] = 2
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'DictView' object does not support item assignment

# Modifications of the original collection are visible in the view:
>>> dict1['a'] = 2
>>> dictview1['a']
2

Example with lists:

$ python
>>> from immutable_views import ListView
>>> list1 = ['a', 'b']
>>> listview1 = ListView(list1)

# Read-only access to the view is supported:
>>> listview1[0]
'a'

# Modifying the view is rejected:
>>> listview1[0] = 'c'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'ListView' object does not support item assignment

# Modifications of the original collection are visible in the view:
>>> list1[0] = 'c'
>>> listview1[0]
'c'

Example with sets:

$ python
>>> from immutable_views import SetView
>>> set1 = {'a', 'b'}
>>> setview1 = SetView(set1)

# Read-only access to the view is supported:
>>> 'a' in setview1
True

# Modifying the view is rejected:
>>> setview1.add('c')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'SetView' object has no attribute 'add'

# Modifications of the original collection are visible in the view:
>>> set1.add('c')
>>> 'c' in setview1
True

Note that there are several packages on Pypi that provide immutable collections, but they all are collections on their own, and not views on other collections. Here is a notable subset of such packages:

• immutables

• pyimmutable

• frozenordereddict

• immutabledict

• frozendict

• itypes

• HashableDict

• shoobx.immutable

• immutable-collection

• Dict-Path-Immutable

Documentation and change log

• Documentation

• Change log

License

The immutable-views project is provided under the Apache Software License 2.0.