frozendict¶
About¶
frozendict
is an immutable wrapper around dictionaries that implements the
complete mapping interface. It can be used as a drop-in replacement for
dictionaries where immutability is desired.
Of course, this is python
, and you can still poke around the object’s
internals if you want.
The frozendict
constructor mimics dict
, and all of the expected
interfaces (iter
, len
, repr
, hash
, getitem
) are provided.
Note that a frozendict
does not guarantee the immutability of its values, so
the utility of the hash
method is restricted by usage.
The only difference is that the copy()
method of frozendict
takes
variable keyword arguments, which will be present as key/value pairs in the new,
immutable copy.
Usage¶
>>> from cawdrey import frozendict
>>>
>>> fd = frozendict({ 'hello': 'World' })
>>>
>>> print fd
<frozendict {'hello': 'World'}>
>>>
>>> print fd['hello']
'World'
>>>
>>> print fd.copy(another='key/value')
<frozendict {'hello': 'World', 'another': 'key/value'}>
>>>
In addition, frozendict
supports the +
and -
operands. If you add a
dict
-like object, a new frozendict
will be returned, equal to the old
frozendict
updated with the other object. Example:
>>> frozendict({"Sulla": "Marco", 2: 3}) + {"Sulla": "Marò", 4: 7}
<frozendict {'Sulla': 'Marò', 2: 3, 4: 7}>
>>>
You can also subtract an iterable from a frozendict
. A new frozendict
will be returned, without the keys that are in the iterable. Examples:
>>> frozendict({"Sulla": "Marco", 2: 3}) - {"Sulla": "Marò", 4: 7}
<frozendict {'Sulla': 'Marco', 2: 3}>
>>> frozendict({"Sulla": "Marco", 2: 3}) - [2, 4]
<frozendict {'Sulla': 'Marco'}>
>>>
Some other examples:
>>> from cawdrey import frozendict
>>> fd = frozendict({"Sulla": "Marco", "Hicks": "Bill"})
>>> print(fd)
<frozendict {'Sulla': 'Marco', 'Hicks': 'Bill'}>
>>> print(fd["Sulla"])
Marco
>>> fd["Bim"]
KeyError: 'Bim'
>>> len(fd)
2
>>> "Sulla" in fd
True
>>> "Sulla" not in fd
False
>>> "Bim" in fd
False
>>> hash(fd)
835910019049608535
>>> fd_unhashable = frozendict({1: []})
>>> hash(fd_unhashable)
TypeError: unhashable type: 'list'
>>> fd2 = frozendict({"Hicks": "Bill", "Sulla": "Marco"})
>>> print(fd2)
<frozendict {'Hicks': 'Bill', 'Sulla': 'Marco'}>
>>> fd2 is fd
False
>>> fd2 == fd
True
>>> frozendict()
<frozendict {}>
>>> frozendict(Sulla="Marco", Hicks="Bill")
<frozendict {'Sulla': 'Marco', 'Hicks': 'Bill'}>
>>> frozendict((("Sulla", "Marco"), ("Hicks", "Bill")))
<frozendict {'Sulla': 'Marco', 'Hicks': 'Bill'}>
>>> fd.get("Sulla")
'Marco'
>>> print(fd.get("God"))
None
>>> tuple(fd.keys())
('Sulla', 'Hicks')
>>> tuple(fd.values())
('Marco', 'Bill')
>>> tuple(fd.items())
(('Sulla', 'Marco'), ('Hicks', 'Bill'))
>>> iter(fd)
<dict_keyiterator object at 0x7feb75c49188>
>>> frozendict.fromkeys(["Marco", "Giulia"], "Sulla")
<frozendict {'Marco': 'Sulla', 'Giulia': 'Sulla'}>
>>> fd["Sulla"] = "Silla"
TypeError: 'frozendict' object does not support item assignment
>>> del fd["Sulla"]
TypeError: 'frozendict' object does not support item deletion
>>> fd.clear()
AttributeError: 'frozendict' object has no attribute 'clear'
>>> fd.pop("Sulla")
AttributeError: 'frozendict' object has no attribute 'pop'
>>> fd.popitem()
AttributeError: 'frozendict' object has no attribute 'popitem'
>>> fd.setdefault("Sulla")
AttributeError: 'frozendict' object has no attribute 'setdefault'
>>> fd.update({"Bim": "James May"})
AttributeError: 'frozendict' object has no attribute 'update'
API Reference¶
-
class
frozendict
(*args, **kwargs)[source]¶ Bases:
FrozenBase
[~KT
,~VT
]An immutable wrapper around dictionaries that implements the complete
collections.Mapping
interface. It can be used as a drop-in replacement for dictionaries where immutability is desired.Methods:
__add__
(other, *args, **kwargs)If you add a dict-like object, a new frozendict will be returned, equal to the old frozendict updated with the other object.
__and__
(other, *args, **kwargs)Returns a new
frozendict
, that is the intersection betweenself
andother
.__contains__
(key)Return
key in self
.__eq__
(other)Return
self == other
.__getitem__
(key)Return
self[key]
.__iter__
()Iterates over the dictionary’s keys.
__len__
()Returns the number of keys in the dictionary.
__repr__
()Return a string representation of the
DictWrapper
.__sub__
(other, *args, **kwargs)The method will create a new
frozendict
, result of the subtraction by other.copy
(*args, **kwargs)Return a copy of the dictionary.
fromkeys
(iterable[, value])Create a new dictionary with keys from iterable and values set to value.
get
(k[, default])Return the value for
k
ifk
is in the dictionary, elsedefault
.items
()Returns a set-like object providing a view on the
bdict
's items.keys
()Returns a set-like object providing a view on the
bdict
's keys.sorted
(*args[, by])Return a new
frozendict
, with the element insertion sorted.values
()Returns an object providing a view on the
bdict
's values.-
__add__
(other, *args, **kwargs)[source]¶ If you add a dict-like object, a new frozendict will be returned, equal to the old frozendict updated with the other object.
-
__and__
(other, *args, **kwargs)[source]¶ Returns a new
frozendict
, that is the intersection betweenself
andother
.If
other
is a dict-like object, the intersection will contain only the items in common.If
other
is another iterable, the intersection will contain the items ofself
which keys are in other.Iterables of pairs are not managed differently. This is for consistency.
Beware! The final order is dictated by the order of other. This allows the coder to change the order of the original
frozendict
.The last two behaviours breaks voluntarily the
dict.items()
API, for consistency and practical reasons.
-
__getitem__
(key)¶ Return
self[key]
.- Parameters
key (
~KT
)- Return type
~VT
-
__repr__
()¶ Return a string representation of the
DictWrapper
.- Return type
-
__sub__
(other, *args, **kwargs)[source]¶ The method will create a new
frozendict
, result of the subtraction by other.If
other
is adict
-like, the result will have the items of thefrozendict
that are not in common with other.If
other
is another type of iterable, the result will have the items offrozendict
without the keys that are inother
.
-
classmethod
fromkeys
(iterable, value=None)¶ Create a new dictionary with keys from iterable and values set to value.
- Return type
FrozenBase
[~KT
,~VT
]
-
get
(k, default=None)¶ Return the value for
k
ifk
is in the dictionary, elsedefault
.- Parameters
k – The key to return the value for.
default – The value to return if
key
is not in the dictionary. DefaultNone
.
-
items
()¶ Returns a set-like object providing a view on the
bdict
's items.- Return type
AbstractSet
[Tuple
[~KT
,~VT
]]
-
keys
()¶ Returns a set-like object providing a view on the
bdict
's keys.- Return type
AbstractSet
[~KT
]
-
sorted
(*args, by='keys', **kwargs)[source]¶ Return a new
frozendict
, with the element insertion sorted. The signature is the same as the builtinsorted
function, except for the additional parameterby
, that is'keys'
by default and can also be'values'
and'items'
. So the resultingfrozendict
can be sorted by keys, values or items.If you want more complicated sorts read the documentation of
sorted
.The the parameters passed to the
key
function are the keys of thefrozendict
ifby = "keys"
, and are the items otherwise.Note
Sorting by keys and items achieves the same effect. The only difference is when you want to customize the sorting passing a custom
key
function. You could achieve the same result usingby = "values"
, since also sorting by values passes the items to the key function. But this is an implementation detail and you should not rely on it.
-
values
()¶ Returns an object providing a view on the
bdict
's values.- Return type
ValuesView
[~VT
]
-
Copyright¶
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.