dol.dig¶
Layers introspection: walk the layers of a wrapped store and trace a key through them.
Main entry points:
layers: the list of nested layers (found through thestoreattribute), outermost firsttrace_getitem,print_trace_info: the (layer, method, value) steps of a__getitem__
Functions
|
|
|
|
|
The value of |
|
Whether the key |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Yield |
|
A generator of layered steps to inspect a store. |
|
- dol.dig.inner_most(store, arg, method, default=<dol.dig.NoDefault object>)[source]¶
The value of
argafter every layer’smethodhas been applied.>>> from dol import wrap_kvs >>> s = wrap_kvs({'a.txt': 1}, id_of_key=lambda k: k + '.txt') >>> inner_most(s, 'a', '_id_of_key') 'a.txt'
**Raises when no layer defines
method``**, instead of silently returning ``None:>>> inner_most({}, 'a', '_id_of_key') Traceback (most recent call last): ... AttributeError: No layer of dict defines '_id_of_key', so 'a' cannot be resolved. ...
A
Nonehere is the worst possible answer: callers use the result as a key or a path, so it surfaces far from its cause – ashttps://.../None, or asTypeError: expected str, bytes or os.PathLike object, not NoneType.Pass
defaultto opt out of raising:>>> inner_most({}, 'a', '_id_of_key', default=None) is None True
- dol.dig.inner_most_key(store, arg, *, method='_id_of_key', default=<dol.dig.NoDefault object>)¶
The value of
argafter every layer’smethodhas been applied.>>> from dol import wrap_kvs >>> s = wrap_kvs({'a.txt': 1}, id_of_key=lambda k: k + '.txt') >>> inner_most(s, 'a', '_id_of_key') 'a.txt'
**Raises when no layer defines
method``**, instead of silently returning ``None:>>> inner_most({}, 'a', '_id_of_key') Traceback (most recent call last): ... AttributeError: No layer of dict defines '_id_of_key', so 'a' cannot be resolved. ...
A
Nonehere is the worst possible answer: callers use the result as a key or a path, so it surfaces far from its cause – ashttps://.../None, or asTypeError: expected str, bytes or os.PathLike object, not NoneType.Pass
defaultto opt out of raising:>>> inner_most({}, 'a', '_id_of_key', default=None) is None True
- dol.dig.inner_most_val(store, arg, *, method='_data_of_obj', default=<dol.dig.NoDefault object>)¶
The value of
argafter every layer’smethodhas been applied.>>> from dol import wrap_kvs >>> s = wrap_kvs({'a.txt': 1}, id_of_key=lambda k: k + '.txt') >>> inner_most(s, 'a', '_id_of_key') 'a.txt'
**Raises when no layer defines
method``**, instead of silently returning ``None:>>> inner_most({}, 'a', '_id_of_key') Traceback (most recent call last): ... AttributeError: No layer of dict defines '_id_of_key', so 'a' cannot be resolved. ...
A
Nonehere is the worst possible answer: callers use the result as a key or a path, so it surfaces far from its cause – ashttps://.../None, or asTypeError: expected str, bytes or os.PathLike object, not NoneType.Pass
defaultto opt out of raising:>>> inner_most({}, 'a', '_id_of_key', default=None) is None True
- dol.dig.key_in_scope(store, k)[source]¶
Whether the key
kofstoreis inside everyfilt_iterscope of its layers.A side-effect-free probe: nothing is read or written.
kis followed through the layers outermost first; each layer’sfilt_iterpredicates are applied to the key *as it enters that layer*, which is whatstore[k] = vwould do, then_id_of_keymaps it for the layer below. A leaf that has anis_valid_keymethod (e.g.Files) is asked about the innermost key last.>>> from dol import filt_iter, KeyCodecs >>> s = KeyCodecs.prefixed('data/')(filt_iter(dict, filt=lambda k: k.endswith('.txt')))() >>> key_in_scope(s, 'a.txt'), key_in_scope(s, 'a.bin') (True, False)
Here the
filt_itersits below the prefix, so it sees'data/a.txt', not'a.txt':>>> s = KeyCodecs.prefixed('data/')(filt_iter(dict, filt=lambda k: k.startswith('data/a')))() >>> key_in_scope(s, 'a.txt'), key_in_scope(s, 'b.txt') (True, False)
The predicate is the layer’s own, so a predicate that raises on a key raises here too (as
s[k]would), and so does a layer whose_id_of_keyraises for the key (e.g. a key mapping that does not know it): the answer is aboolonly where a write would be accepted or refused, not failed. “Side-effect-free” holds as far as the layers’_id_of_keyand the leaf’sis_valid_keyare.Limits (the probe reads what the layers declare): a layer that maps keys but has no
_id_of_keycannot be followed (TypeError); a layer that looks keys up by its own means while keeping the do-nothing_id_of_key(add_path_access,flatten, whose keys are tuples walked through the inner store) gets a silently wrong answer; so does a subclass that changes the key inside__setitem__before callingsuper().- Return type:
- dol.dig.store_trans_path(store, arg, method)[source]¶
Yield
argtransformed bymethodat each layer, outermost first.Walks the
.storechain, applyingstore.<method>at every layer that defines it.>>> from dol import wrap_kvs >>> s = wrap_kvs({'a.txt': 1}, id_of_key=lambda k: k + '.txt') >>> list(store_trans_path(s, 'a', '_id_of_key')) ['a.txt', 'a.txt']
Yields nothing when no layer defines
method– which is whyinner_most()raises rather than returning theNonethat an empty walk would otherwise produce.>>> list(store_trans_path({}, 'a', '_id_of_key')) []
- dol.dig.trace_getitem(store, k, layer_attrs=('store',))[source]¶
A generator of layered steps to inspect a store.
- Parameters:
store – An instance that has the base.Store interface
k – A key
layer_attrs – The attribute names that should be checked to get the next layer.
- Returns:
A generator of (layer, method, value)
We start with a small dict:
>>> d = {'a.num': '1000', 'b.num': '2000'}
Now let’s add layers to it. For example, with wrap_kvs:
>>> from dol.trans import wrap_kvs
Say that we want the interface to not see the
'.num'strings, and deal with numerical values, not strings.>>> s = wrap_kvs(d, ... key_of_id=lambda x: x[:-len('.num')], ... id_of_key=lambda x: x + '.num', ... obj_of_data=lambda x: int(x), ... data_of_obj=lambda x: str(x) ... ) >>>
Oh, and we want the interface to display upper case keys.
>>> ss = wrap_kvs(s, ... key_of_id=lambda x: x.upper(), ... id_of_key=lambda x: x.lower(), ... )
And we want the numerical unit to be the kilo (that’s 1000):
>>> sss = wrap_kvs(ss, ... obj_of_data=lambda x: x / 1000, ... data_of_obj=lambda x: x * 1000 ... ) >>> >>> dict(sss.items()) {'A': 1.0, 'B': 2.0}
Well, if we had bugs, we’d like to inspect the various layers, and how they transform the data.
# Here's how to do that: # >>> for layer, method, value in trace_getitem(sss, 'A'): # ... print(layer, method, value) # ... # Traceback (most recent call last): # File "<stdin>", line 1, in <module> # NameError: name 'trace_getitem' is not defined
>>> from dol.dig import trace_getitem >>> >>> for layer, method, value in trace_getitem(sss, 'A'): ... print(layer, method, value) ... {'a.num': '1000', 'b.num': '2000'} _id_of_key A {'a.num': '1000', 'b.num': '2000'} _id_of_key A {'a.num': '1000', 'b.num': '2000'} _id_of_key a {'a.num': '1000', 'b.num': '2000'} _id_of_key a {'a.num': '1000', 'b.num': '2000'} _id_of_key a.num {'a.num': '1000', 'b.num': '2000'} _id_of_key a.num {'a.num': '1000', 'b.num': '2000'} __getitem__ 1000 {'a.num': '1000', 'b.num': '2000'} _obj_of_data 1000 {'a.num': '1000', 'b.num': '2000'} _obj_of_data 1000 {'a.num': '1000', 'b.num': '2000'} _obj_of_data 1000 {'a.num': '1000', 'b.num': '2000'} _obj_of_data 1000 {'a.num': '1000', 'b.num': '2000'} _obj_of_data 1000 {'a.num': '1000', 'b.num': '2000'} _obj_of_data 1.0
- dol.dig.unravel_key(store, arg, *, method='_id_of_key')¶
Yield
argtransformed bymethodat each layer, outermost first.Walks the
.storechain, applyingstore.<method>at every layer that defines it.>>> from dol import wrap_kvs >>> s = wrap_kvs({'a.txt': 1}, id_of_key=lambda k: k + '.txt') >>> list(store_trans_path(s, 'a', '_id_of_key')) ['a.txt', 'a.txt']
Yields nothing when no layer defines
method– which is whyinner_most()raises rather than returning theNonethat an empty walk would otherwise produce.>>> list(store_trans_path({}, 'a', '_id_of_key')) []
- dol.dig.unravel_val(store, arg, *, method='_data_of_obj')¶
Yield
argtransformed bymethodat each layer, outermost first.Walks the
.storechain, applyingstore.<method>at every layer that defines it.>>> from dol import wrap_kvs >>> s = wrap_kvs({'a.txt': 1}, id_of_key=lambda k: k + '.txt') >>> list(store_trans_path(s, 'a', '_id_of_key')) ['a.txt', 'a.txt']
Yields nothing when no layer defines
method– which is whyinner_most()raises rather than returning theNonethat an empty walk would otherwise produce.>>> list(store_trans_path({}, 'a', '_id_of_key')) []