dol.explicit

Stores whose keys are given explicitly, with values fetched lazily from a source.

Main entry points:

• KeysReader: a collection of keys plus a getter(src, key)

• ExplicitKeysSource: explicit keys plus a function reading the value for a key

• ExplicitKeysStore: wrap a store so that its keys come from an explicit iterable

• ExplicitKeyMap: a key mapper given as explicit dicts

  >>> from dol.explicit import KeysReader
  >>> r = KeysReader({'apple': 'pie', 'banana': 'split'}, ['banana'], lambda src, k: src[k])
  >>> list(r), r['banana']
  (['banana'], 'split')
  

Classes

ExplicitKeyMap(*[, key_of_id, id_of_key])	A key mapper given as explicit key_of_id/id_of_key dicts (one is enough; the other is derived, and both are checked to be inverse of each other).
ExplicitKeymapReader(store[, key_of_id, ...])	Wrap a store (instance) so that it gets it's keys from an explicit iterable of keys.
ExplicitKeys(key_collection)	dol.base.Keys implementation that gets it's keys explicitly from a collection given at initialization time.
ExplicitKeysSource(key_collection, _obj_of_key)	An object source that uses an explicit keys collection and a specified function to read contents for a key.
ExplicitKeysStore(store, key_collection)	Wrap a store (instance) so that it gets it's keys from an explicit iterable of keys.
KeysReader(src, key_collection, getter, *[, ...])	Mapping defined by keys with a getter function that gets values from keys.
ObjDumper(save_data_to_key[, data_of_obj])

class dol.explicit.ExplicitKeyMap(*, key_of_id=None, id_of_key=None)

Bases: object

A key mapper given as explicit key_of_id/id_of_key dicts (one is enough; the other is derived, and both are checked to be inverse of each other). Provides the _key_of_id/_id_of_key methods that kv_wrap looks for.

class dol.explicit.ExplicitKeymapReader(store, key_of_id=None, id_of_key=None)

Bases: ExplicitKeys, Store

Wrap a store (instance) so that it gets it’s keys from an explicit iterable of keys.

>>> s = {'a': 1, 'b': 2, 'c': 3, 'd': 4}
>>> id_of_key = {'A': 'a', 'C': 'c'}
>>> ss = ExplicitKeymapReader(s, id_of_key=id_of_key)
>>> list(ss)
['A', 'C']
>>> ss['C']  # will look up 'C', find 'c', and call the store on that.
3

class dol.explicit.ExplicitKeys(key_collection)

Bases: Collection

dol.base.Keys implementation that gets it’s keys explicitly from a collection given at initialization time. The key_collection must be a collections.abc.Collection (such as list, tuple, set, etc.)

>>> keys = ExplicitKeys(key_collection=['foo', 'bar', 'alice'])
>>> 'foo' in keys
True
>>> 'not there' in keys
False
>>> list(keys)
['foo', 'bar', 'alice']

class dol.explicit.ExplicitKeysSource(key_collection, _obj_of_key)

Bases: ExplicitKeys, ObjReader, KvReader

An object source that uses an explicit keys collection and a specified function to read contents for a key.

>>> s = ExplicitKeysSource([1, 2, 3], str)
>>> list(s)
[1, 2, 3]
>>> list(s.values())
['1', '2', '3']

Main functionality equivalent to recipe:

>>> def explicit_keys_source(key_collection, _obj_of_key):
...     from dol.trans import wrap_kvs
...     return wrap_kvs({k: k for k in key_collection}, obj_of_data=_obj_of_key)

>>> s = explicit_keys_source([1, 2, 3], str)
>>> list(s)
[1, 2, 3]
>>> list(s.values())
['1', '2', '3']

class dol.explicit.ExplicitKeysStore(store, key_collection)

Bases: ExplicitKeys, Store

Wrap a store (instance) so that it gets it’s keys from an explicit iterable of keys.

>>> s = {'a': 1, 'b': 2, 'c': 3, 'd': 4}
>>> list(s)
['a', 'b', 'c', 'd']
>>> ss = ExplicitKeysStore(s, ['d', 'a'])
>>> len(ss)
2
>>> list(ss)
['d', 'a']
>>> list(ss.values())
[4, 1]
>>> ss.head()
('d', 4)

class dol.explicit.KeysReader(src, key_collection, getter, *, key_error_msg=<built-in method format of str object>)

Bases: Mapping

Mapping defined by keys with a getter function that gets values from keys.

KeysReader is particularly useful in cases where you want to have a mapping that lazy-load values for keys from an explicit collection.

Keywords: Lazy-evaluation, Mapping

Parameters:

• src (TypeVar(Source)) – The source where values will be extracted from.

• key_collection (Collection[TypeVar(KT)]) – A collection of keys that will be used to extract values from src.

• getter (Callable[[TypeVar(Source), TypeVar(KT)], TypeVar(VT)]) – A function that takes a source and a key, and returns the value for that key.

• key_error_msg (Callable[[TypeVar(Source), TypeVar(KT)], str]) – A function that takes a source and a key, and returns an error message.

Example

>>> src = {'apple': 'pie', 'banana': 'split', 'carrot': 'cake'}
>>> key_collection = ['carrot', 'apple']
>>> getter = lambda src, key: src[key]
>>> key_reader = KeysReader(src, key_collection, getter)

Note that the only the keys mentioned by key_collection will be iterated through, and in the order they are mentioned in key_collection.

>>> list(key_reader)
['carrot', 'apple']

>>> key_reader['apple']
'pie'
>>> key_reader['banana']
Traceback (most recent call last):
...
KeyError: "Key 'banana' was not found....key_collection attribute)"

Let’s take the same src and key_collection, but with a different getter and key_error_msg:

Note that a key_error_msg must be a function that takes a src and a key, in that order and with those argument names. Say you wanted to not use the src in your message. You would still have to write a function that takes src as the first argument.

>>> key_error_msg = lambda src, key: f"Key {key} was not found"  # no source information

>>> getter = lambda src, key: f"Value for {key} in {src}: {src[key]}"
>>> key_reader = KeysReader(src, key_collection, getter, key_error_msg=key_error_msg)
>>> list(key_reader)
['carrot', 'apple']
>>> key_reader['apple']
"Value for apple in {'apple': 'pie', 'banana': 'split', 'carrot': 'cake'}: pie"
>>> key_reader['banana']
Traceback (most recent call last):
...
KeyError: "Key banana was not found"