pyimmutable API

ImmutableDict

class pyimmutable.ImmutableDict(mapping_or_iterable=(), **kwargs)

Return an ImmutableDict object initialized from a mapping or iterable (if given) and/or keyword arguments. If called with no arguments, returns the empty ImmutableDict.

An ImmutableDict is, as the name suggests, immutable. The data stored in it remains the same for all of its lifetime. An ImmutableDict has methods to create further ImmutableDict objects as modifications of the current one.

There is only ever one ImmutableDict object that contains the same data. For example:

>>> d1 = ImmutableDict().set("a", 1).set("b", 2)
>>> d2 = ImmutableDict(a=1, b=2)
>>> d1 is d2
True

discard(key)

Return a copy with key removed.

Returns self if key is not present.

get(key, default=None)

Return the value for key if key is in the dictionary, else default.

isImmutableJson

True if self only contains immutable, JSON-serializable data.

For this to be True, the ImmutableDict must only have keys of type str. Also, all values must be either None, or of type bool, str, int, float, or be an ImmutableDict or an ImmutableList which itself has isImmutableJson set to True.

items()

Return an iterator over (key, value) tuples.

keys()

Return an iterator over the keys in this ImmutableDict.

meta

A unique dictionary attached to this ImmutableDict

This property returns a Python dictionary that is attached to the ImmutableDict object. The same dictionary is used for the entire lifetime of this ImmutableDict object. All references to an ImmutableDict with the same contents indeed refer to the same ImmutableDict object, and therefore all share the same meta dictionary. ImmutableDict objects may be garbage-collected when there no reference is kept to them, and at that point the meta dictionary gets deleted, too.

pop(key)

Return a copy with key removed.

Raises KeyError if key is not present.

set(key, value)

Return a copy with key set to value.

update(mapping_or_iterable=(), **kwargs)

Return a new ImmutableDict on the basis of this one, with keys updated from a mapping or iterable of (key, value) tuples and/or keyword arguments.

values()

Return an iterator over the values in this ImmutableDict.

ImmutableList

class pyimmutable.ImmutableList(sequence=())

Return an ImmutableList object initialized from sequence (if given). If called with no arguments, returns the empty ImmutableList.

An ImmutableList is, as the name suggests, immutable. The data stored in it remains the same for all of its lifetime. An ImmutableList has methods to create further ImmutableList objects as modifications of the current one.

There is only ever one ImmutableList object that contains the same data. For example:

>>> l1 = ImmutableList().append('a').append(2)
>>> l2 = ImmutableList(['a', 2])
>>> l1 is l2
True

append(value)

Return a copy with the given value appended.

count(value)

Return number of occurrences of value.

extend(iterable)

Return a copy extended by appending elements from iterable.

index(value, start=0, stop=9223372036854775807)

Return first index of value.

Raises ValueError if value is not present.

isImmutableJson

True if this ImmutableList only contains immutable, JSON-serializable data.

For this to be True, the ImmutableList must only contain values that are either None, or of type bool, str, int, float, or are an ImmutableDict or an immutableList which itself has isImmutableJson set to True.

meta

This property returns a Python dictionary that is attached to the ImmutableList object. The same dictionary is used for the entire lifetime of this ImmutableList object. All references to an ImmutableList with the same contents indeed refer to the same ImmutableList object, and therefore all share the same meta dictionary. ImmutableList objects may be garbage-collected when there no reference is kept to them, and at that point the meta dictionary gets deleted, too.

set(index, value)

Return a copy with item index set to value.

Raises IndexError if index is outside the range of existing elements.

Auxiliary Functions

pyimmutable.json_dump(obj, fp, *, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False, **kw)

Serialize obj` as a JSON and write to fp.

This function makes a deep copy of the object, replacing all sequences (including ImmutableList) with lists and all mappings (including ImmutableDict) with dicts. The result is passed to json.dump.

All arguments are passed to json.dump. This function may be replaced by an efficient, native implementation in a later version of pyimmutable, which may not support the same keyword arguments.

pyimmutable.json_dumps(obj, *, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False, **kw)

Serialize obj to a JSON formatted str.

This function makes a deep copy of the object, replacing all sequences (including ImmutableList) with lists and all mappings (including ImmutableDict) with dicts. The result is passed to json.dumps.

All arguments are passed to json.dumps. This function may be replaced by an efficient, native implementation in a later version of pyimmutable, which may not support the same keyword arguments.

pyimmutable.json_load(fp, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)

Read JSON from fp and deserialize as immutable data.

This function calls json.load and then builds a (potentially nested) structure of ImmutableDict/ImmutableList objects from the returned object.

All arguments are passed to json.load. This function may be replaced by an efficient, native implementation in a later version of pyimmutable, which may not support the same keyword arguments.

pyimmutable.json_loads(s, *, encoding=None, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)

Deserialize JSON string as immutable data.

This function calls json.loads and then builds a (potentially nested) structure of ImmutableDict/ImmutableList objects from the returned object.

All arguments are passed to json.loads. This function may be replaced by an efficient, native implementation in a later version of pyimmutable, which may not support the same keyword arguments.

pyimmutable.make_immutable(object)

Make a deep copy of nested sequences/mappings using list and dict.

A nested structure using ImmutableDict/ImmutableList objects is turned into an equivalent structure using dict and list, e.g. for passing to json.dump.

pyimmutable.make_mutable(object)

Make a deep copy using ImmutableList and ImmutableDict.

A nested structure using is turned into one using ImmutableList for every sequence and ImmutableDict for every mapping.