Developer Interface

Maps

class maps.FrozenMap(*args, **kwargs)

An immutable, hashable key-value mapping accessible via bracket-notation (i.e. __getitem__).

Parameters:

• args – Position arguments in the same form as the dict constructor.
• kwargs – Keyword arguments in the same form as the dict constructor.

Usage:

>>> import maps
>>> fm = maps.FrozenMap({'a': 1, 'b': 2})
>>> fm['a']
1
>>> list(fm.items())
[('a', 1), ('b', 2)]
>>> len(fm)
2
>>> hash(fm)
3212389899479848432

classmethod recurse(obj, list_fn=<class 'tuple'>, object_fn=None)

Recursively create FrozenMap s when collections.Mapping are encountered.

Parameters:

• obj – Object to be recursively converted.
• list_fn (func) – Conversion function applied to any collections.Sequence s and collections.Set s encountered. Defaults to tuple.
• object_fn (func) – Conversion function applied to all other objects encountered. Defaults to the identity function.

Usage:

>>> import maps
>>> fm = maps.FrozenMap.recurse({'a': 1, 'b': [2, {'c': 3}]})
>>> fm.b[1]
FrozenMap(c=3)

class maps.FixedKeyMap(*args, **kwargs)

A key-value mapping with a fixed set of keys whose items are accessible via bracket-notation (i.e. __getitem__ and __setitem__). Though the set of keys is immutable, the corresponding values can be edited.

Parameters:

• args – Position arguments in the same form as the dict constructor.
• kwargs – Keyword arguments in the same form as the dict constructor.

Usage:

>>> import maps
>>> fkm = maps.FixedKeyMap({'a': 1, 'b': 2})
>>> fkm['a']
1
>>> fkm['b'] += 10
>>> fkm['b']
12
>>> list(fkm.items())
[('a', 1), ('b', 12)]
>>> len(fkm)
2

classmethod recurse(obj, list_fn=None, object_fn=None)

Recursively create FixedKeyMap s when collections.Mapping are encountered.

Parameters:

• obj – Object to be recursively converted.
• list_fn (func) – Conversion function applied to any collections.Sequence s and collections.Set s encountered. Defaults to the identity function.
• object_fn (func) – Conversion function applied to all other objects encountered. Defaults to the identity function.

Usage:

>>> import maps
>>> fkm = maps.FixedKeyMap.recurse({'a': 1, 'b': [2, {'c': 3}]})
>>> fkm.b[1]
FixedKeyMap(c=3)

Named Maps

maps.namedfrozen(typename, fields, defaults={})

Creates a new class that inherits from maps.FrozenMap that has the specified fields as keys. Fields are accessible via bracket-notation (i.e. __getitem__) as well as dot-notation (i.e. __getattr__). Instances of the returned class are immutable.

Parameters:

• typename (str) – Name of the new Map class
• fields (iterable) – Names of the fields
• defaults (mapping) – Maps default values to fields

Raises:

ValueError – if the type name or field names or defaults provided are not properly formatted

Returns:

The newly created class

Return type:

class

Usage:

>>> import maps
>>> RGB = maps.namedfrozen('RGB', ['red', 'green', 'blue'], defaults={'green': 127, 'blue': 80})
>>> coral = RGB(255)
>>> coral['red']
255
>>> coral.green
127

maps.namedfixedkey(typename, fields, defaults={})

Creates a new class that inherits from maps.FixedKeyMap that has the speciefied fields as keys. Fields are accessible via bracket-notation (i.e. __getitem__) as well as dot-notation (i.e. __getattr__). Instances of the returned class have a fixed set of keys, but the values corresponding to those keys can be edited.

Parameters:

• typename (str) – Name of the new Map class
• fields (iterable) – Names of the fields
• defaults (mapping) – Maps default values to fields

Raises:

ValueError – if the type name or field names or defaults provided are not properly formatted

Returns:

The newly created class

Return type:

class

Usage:

>>> import maps
>>> Person = maps.namedfixedkey('Person', ['name', 'gender', 'age'], defaults={'age': 40})
>>> bob = Person('bob', 'male')
>>> bob['name']
'bob'
>>> bob.gender
'male'
>>> bob.age += 1
>>> bob.age
41

class maps.NamedDict

A subclass of dict whose items can be accessed via standard bracket-notation (i.e. __getitem and __setitem__) as well as dot-notation (i.e. __getattr__ and __setattr__).

Usage:

>>> import maps
>>> nd = maps.NamedDict({'a': 1, 'b': 2})
>>> nd['a']
1
>>> nd.b
2
>>> nd['c'] = 3
>>> nd.c
3
>>> nd.d = 4
>>> nd.d
4
>>> d = dict(nd)
>>> d
{'a': 1, 'b': 2, 'c': 3}

__getattr__(name)

Retrieves the corresponding value for the specified key via dot-notation.

Parameters:name (str) – Key for desired item Raises:KeyError – if the specified key is not in the dictionary. Returns:Value of desired item

__setattr__(name, value)

Sets the value for the specified key via dot-notation.

Parameters:

• name (str) – Key for desired item
• value – New value of desired item

classmethod recurse(obj, list_fn=None, object_fn=None)

Recursively create NamedDict s when collections.Mapping are encountered.

Parameters:

• obj – Object to be recursively converted.
• list_fn (func) – Conversion function applied to any collections.Sequence s and collections.Set s encountered. Defaults to the identity function.
• object_fn (func) – Conversion function applied to all other objects encountered. Defaults to the identity function.

Usage:

>>> import maps
>>> fm = maps.NamedDict.recurse({'a': 1, 'b': [2, {'c': 3}]})
>>> fm.b[1]
FrozenMap(c=3)

Named Map MetaClasses

The Named Maps section details maps.namedfrozen() and maps.namedfixedkey(), which are the recommended way to instantiate Named Map classes. Under the hood, those 2 functions leverage the metaclasses detailed below.

class maps.NamedFrozenMapMeta(typename, fields=[], defaults={})

Returns a new maps.FrozenMap subclass named typename. The new subclass is used to create dict-like objects that have fields accessible by attribute lookup as well as being indexable by name and iterable. Instances of the subclass also have a helpful docstring (with typename and field_names) and a helpful __repr__() method which lists the mapping contents in a name=value format.

field_names can be a sequence of strings such as ['x', 'y'].

Any valid Python identifier may be used for a fieldname except for names starting with an underscore. Valid identifiers consist of letters, digits, and underscores but do not start with a digit or underscore and cannot be a keyword such as class, for, return, global, pass, or raise.

This metaclass injects 3 methods into the subclass: __getattr__, __setattr__, and __repr__.

1. __getattr__ attempts to retrieve attributes from an instance’s underlying _data dictionary, raising AttributeError if the attribute is not found.

2. __setattr__ raises TypeError unless the attribute name has a leading underscore, in which case the attribute will be set normally.

3. __repr__ simply replaces FrozenMap with the name of the instantiated class.

maps.namedfrozen() provides a convenient alias for calling this metaclass.

Parameters:

• typename (str) – Name for the new class
• fields (iterable) – Names for the fields of the new class
• defaults (mapping) – Maps default values to fields of the new class

Raises:

ValueError – if the type name or field names or defaults provided are not properly formatted

Returns:

Newly created subclass of maps.FrozenMap

static _getattr(name)

Retrieves attribute by name.

Parameters:name (str) – Name of the desired attribute Raises:AttributeError – if an attribute with the specified name cannot be found Returns:Desired attribute

static _setattr(name, value)

Raises a TypeError as attribute assignment is not supported.

Raises:TypeError –

class maps.NamedFixedKeyMapMeta(typename, fields=[], defaults={})

Returns a new maps.FixedKeyMap subclass named typename. The new subclass is used to create dict-like objects that have fields accessible by attribute lookup as well as being indexable by name and iterable. Instances of the subclass also have a helpful docstring (with typename and field_names) and a helpful __repr__() method which lists the mapping contents in a name=value format.

field_names can be a sequence of strings such as ['x', 'y'].

Any valid Python identifier may be used for a fieldname except for names starting with an underscore. Valid identifiers consist of letters, digits, and underscores but do not start with a digit or underscore and cannot be a keyword such as class, for, return, global, pass, or raise.

This metaclass injects 3 methods into the subclass: __getattr__, __setattr__, and __repr__.

1. __getattr__ attempts to retrieve attributes from an instance’s underlying _data dictionary, raising AttributeError if the attribute is not found.

2. __setattr__ attempts to set the value for the specified attribute, but raises TypeError if the attribute is not part of the fixed key set. If the attribute name has a leading underscore, these checks are skipped and the value is set normally.

3. __repr__ simply replaces FixedKeyMap with the name of the instantiated class.

maps.namedfixedkey() provides a convenient alias for calling this metaclass.

Parameters:

• typename (str) – Name for the new class
• fields (iterable) – Names for the fields of the new class
• defaults (mapping) – Maps default values to fields of the new class

Raises:

ValueError – if the type name or field names or defaults provided are not properly formatted

Returns:

Newly created subclass of maps.FixedKeyMap

static _getattr(name)

Retrieves attribute by name.

Parameters:name (str) – Name of the desired attribute Raises:AttributeError – if an attribute with the specified name cannot be found Returns:Desired attribute

static _setattr(name, value)

Sets the value for the specified attribute if the attribute name is part of the fixed key set.

Raises:TypeError – if the attribute name is not part of the fixed key set