cachebind 1.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- cachebind/__init__.py +121 -0
- cachebind/indexes/__init__.py +61 -0
- cachebind/indexes/_breadcrumb.py +10 -0
- cachebind/indexes/_builder.py +171 -0
- cachebind/indexes/_serializer.py +17 -0
- cachebind/indexes/base.py +51 -0
- cachebind/indexes/evict.py +21 -0
- cachebind/indexes/key_value/__init__.py +14 -0
- cachebind/indexes/key_value/async_index.py +145 -0
- cachebind/indexes/key_value/base.py +30 -0
- cachebind/indexes/key_value/builder.py +170 -0
- cachebind/indexes/key_value/index.py +142 -0
- cachebind/indexes/ordered_sets/__init__.py +17 -0
- cachebind/indexes/ordered_sets/async_index.py +221 -0
- cachebind/indexes/ordered_sets/base.py +38 -0
- cachebind/indexes/ordered_sets/builder.py +146 -0
- cachebind/indexes/ordered_sets/index.py +218 -0
- cachebind/indexes/registry.py +38 -0
- cachebind/indexes/sets/__init__.py +14 -0
- cachebind/indexes/sets/async_index.py +124 -0
- cachebind/indexes/sets/base.py +24 -0
- cachebind/indexes/sets/builder.py +146 -0
- cachebind/indexes/sets/index.py +121 -0
- cachebind/indexes/tries/__init__.py +14 -0
- cachebind/indexes/tries/async_index.py +113 -0
- cachebind/indexes/tries/base.py +25 -0
- cachebind/indexes/tries/builder.py +141 -0
- cachebind/indexes/tries/index.py +113 -0
- cachebind/serializers/__init__.py +29 -0
- cachebind/serializers/bool_serializer.py +21 -0
- cachebind/serializers/dataclass_serializer.py +102 -0
- cachebind/serializers/datetime_serializer.py +22 -0
- cachebind/serializers/dict_serializer.py +29 -0
- cachebind/serializers/float_serializer.py +18 -0
- cachebind/serializers/int_serializer.py +20 -0
- cachebind/serializers/noop_serializer.py +19 -0
- cachebind/serializers/pydantic_serializer.py +29 -0
- cachebind/serializers/serializer.py +24 -0
- cachebind/serializers/str_serializer.py +13 -0
- cachebind/serializers/uuid_serializer.py +22 -0
- cachebind/storage/__init__.py +67 -0
- cachebind/storage/_redis.py +80 -0
- cachebind/storage/key_value/__init__.py +37 -0
- cachebind/storage/key_value/async_redis_hash_storage.py +73 -0
- cachebind/storage/key_value/async_redis_string_storage.py +72 -0
- cachebind/storage/key_value/async_storage.py +76 -0
- cachebind/storage/key_value/redis_hash_storage.py +73 -0
- cachebind/storage/key_value/redis_string_storage.py +72 -0
- cachebind/storage/key_value/storage.py +74 -0
- cachebind/storage/ordered_sets/__init__.py +29 -0
- cachebind/storage/ordered_sets/_values.py +60 -0
- cachebind/storage/ordered_sets/async_redis_ordered_set_storage.py +91 -0
- cachebind/storage/ordered_sets/async_storage.py +89 -0
- cachebind/storage/ordered_sets/redis_ordered_set_storage.py +88 -0
- cachebind/storage/ordered_sets/storage.py +85 -0
- cachebind/storage/sets/__init__.py +27 -0
- cachebind/storage/sets/async_redis_set_storage.py +54 -0
- cachebind/storage/sets/async_storage.py +49 -0
- cachebind/storage/sets/redis_set_storage.py +52 -0
- cachebind/storage/sets/storage.py +49 -0
- cachebind/storage/tries/__init__.py +27 -0
- cachebind/storage/tries/_reply.py +20 -0
- cachebind/storage/tries/_values.py +36 -0
- cachebind/storage/tries/async_redis_trie_storage.py +81 -0
- cachebind/storage/tries/async_storage.py +78 -0
- cachebind/storage/tries/redis_trie_storage.py +79 -0
- cachebind/storage/tries/storage.py +78 -0
- cachebind/tagging/__init__.py +19 -0
- cachebind/tagging/breadcrumbs/__init__.py +11 -0
- cachebind/tagging/breadcrumbs/colon_breadcrumbs.py +20 -0
- cachebind/tagging/breadcrumbs/noop_breadcrumbs.py +15 -0
- cachebind/tagging/breadcrumbs/protocol.py +15 -0
- cachebind/tagging/tag_keeper/__init__.py +12 -0
- cachebind/tagging/tag_keeper/_keys.py +10 -0
- cachebind/tagging/tag_keeper/async_set_tag_keeper.py +47 -0
- cachebind/tagging/tag_keeper/protocol.py +37 -0
- cachebind/tagging/tag_keeper/set_tag_keeper.py +47 -0
- cachebind-1.0.0.dist-info/METADATA +171 -0
- cachebind-1.0.0.dist-info/RECORD +81 -0
- cachebind-1.0.0.dist-info/WHEEL +4 -0
- cachebind-1.0.0.dist-info/licenses/LICENSE +21 -0
cachebind/__init__.py
ADDED
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
"""Cachebind."""
|
|
2
|
+
|
|
3
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
4
|
+
|
|
5
|
+
from cachebind.indexes import (
|
|
6
|
+
AsyncEvictableIndex,
|
|
7
|
+
AsyncKeyValueIndex,
|
|
8
|
+
AsyncOrderedSetIndex,
|
|
9
|
+
AsyncSetIndex,
|
|
10
|
+
AsyncTrieIndex,
|
|
11
|
+
EvictableIndex,
|
|
12
|
+
Index,
|
|
13
|
+
IndexRegistry,
|
|
14
|
+
KeyValueBase,
|
|
15
|
+
KeyValueIndex,
|
|
16
|
+
OrderedSetBase,
|
|
17
|
+
OrderedSetIndex,
|
|
18
|
+
SetBase,
|
|
19
|
+
SetIndex,
|
|
20
|
+
TrieBase,
|
|
21
|
+
TrieIndex,
|
|
22
|
+
build_async_key_value_index,
|
|
23
|
+
build_async_ordered_set_index,
|
|
24
|
+
build_async_set_index,
|
|
25
|
+
build_async_trie_index,
|
|
26
|
+
build_key_value_index,
|
|
27
|
+
build_ordered_set_index,
|
|
28
|
+
build_set_index,
|
|
29
|
+
build_trie_index,
|
|
30
|
+
get_registry,
|
|
31
|
+
)
|
|
32
|
+
from cachebind.tagging import (
|
|
33
|
+
AsyncSetTagKeeper,
|
|
34
|
+
AsyncTagKeeper,
|
|
35
|
+
Breadcrumbs,
|
|
36
|
+
ColonBreadcrumbs,
|
|
37
|
+
NoopBreadcrumbs,
|
|
38
|
+
SetTagKeeper,
|
|
39
|
+
TagKeeper,
|
|
40
|
+
)
|
|
41
|
+
from cachebind.serializers import (
|
|
42
|
+
BoolSerializer,
|
|
43
|
+
DataclassSerializer,
|
|
44
|
+
DatetimeSerializer,
|
|
45
|
+
DictSerializer,
|
|
46
|
+
FloatSerializer,
|
|
47
|
+
IntSerializer,
|
|
48
|
+
NoopSerializer,
|
|
49
|
+
Serializer,
|
|
50
|
+
StrSerializer,
|
|
51
|
+
UuidSerializer,
|
|
52
|
+
)
|
|
53
|
+
from cachebind.storage import (
|
|
54
|
+
AsyncKeyValueStorage,
|
|
55
|
+
AsyncOrderedSetStorage,
|
|
56
|
+
AsyncSetStorage,
|
|
57
|
+
AsyncTrieStorage,
|
|
58
|
+
KeyValueStorage,
|
|
59
|
+
OrderedSetStorage,
|
|
60
|
+
SetStorage,
|
|
61
|
+
TrieStorage,
|
|
62
|
+
)
|
|
63
|
+
|
|
64
|
+
try:
|
|
65
|
+
__version__ = version("cachebind")
|
|
66
|
+
except PackageNotFoundError:
|
|
67
|
+
__version__ = "0.0.0"
|
|
68
|
+
|
|
69
|
+
__all__ = [
|
|
70
|
+
"AsyncEvictableIndex",
|
|
71
|
+
"AsyncKeyValueIndex",
|
|
72
|
+
"AsyncKeyValueStorage",
|
|
73
|
+
"AsyncOrderedSetIndex",
|
|
74
|
+
"AsyncOrderedSetStorage",
|
|
75
|
+
"AsyncSetIndex",
|
|
76
|
+
"AsyncSetStorage",
|
|
77
|
+
"AsyncSetTagKeeper",
|
|
78
|
+
"AsyncTagKeeper",
|
|
79
|
+
"AsyncTrieIndex",
|
|
80
|
+
"AsyncTrieStorage",
|
|
81
|
+
"BoolSerializer",
|
|
82
|
+
"Breadcrumbs",
|
|
83
|
+
"ColonBreadcrumbs",
|
|
84
|
+
"NoopBreadcrumbs",
|
|
85
|
+
"DataclassSerializer",
|
|
86
|
+
"DatetimeSerializer",
|
|
87
|
+
"DictSerializer",
|
|
88
|
+
"FloatSerializer",
|
|
89
|
+
"EvictableIndex",
|
|
90
|
+
"Index",
|
|
91
|
+
"IndexRegistry",
|
|
92
|
+
"IntSerializer",
|
|
93
|
+
"NoopSerializer",
|
|
94
|
+
"KeyValueBase",
|
|
95
|
+
"KeyValueIndex",
|
|
96
|
+
"KeyValueStorage",
|
|
97
|
+
"OrderedSetBase",
|
|
98
|
+
"OrderedSetIndex",
|
|
99
|
+
"OrderedSetStorage",
|
|
100
|
+
"Serializer",
|
|
101
|
+
"SetBase",
|
|
102
|
+
"SetIndex",
|
|
103
|
+
"SetStorage",
|
|
104
|
+
"SetTagKeeper",
|
|
105
|
+
"TagKeeper",
|
|
106
|
+
"StrSerializer",
|
|
107
|
+
"UuidSerializer",
|
|
108
|
+
"TrieBase",
|
|
109
|
+
"TrieIndex",
|
|
110
|
+
"TrieStorage",
|
|
111
|
+
"__version__",
|
|
112
|
+
"build_async_key_value_index",
|
|
113
|
+
"build_async_ordered_set_index",
|
|
114
|
+
"build_async_set_index",
|
|
115
|
+
"build_async_trie_index",
|
|
116
|
+
"build_key_value_index",
|
|
117
|
+
"build_ordered_set_index",
|
|
118
|
+
"build_set_index",
|
|
119
|
+
"build_trie_index",
|
|
120
|
+
"get_registry",
|
|
121
|
+
]
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
"""Indexes bind a value to storage and register that binding by key."""
|
|
2
|
+
|
|
3
|
+
from cachebind.indexes.base import Index, get_registry
|
|
4
|
+
from cachebind.indexes.evict import AsyncEvictableIndex, EvictableIndex
|
|
5
|
+
from cachebind.indexes.key_value import (
|
|
6
|
+
AsyncKeyValueIndex,
|
|
7
|
+
KeyValueBase,
|
|
8
|
+
KeyValueIndex,
|
|
9
|
+
build_async_key_value_index,
|
|
10
|
+
build_key_value_index,
|
|
11
|
+
)
|
|
12
|
+
from cachebind.indexes.ordered_sets import (
|
|
13
|
+
AsyncOrderedSetIndex,
|
|
14
|
+
OrderedSetBase,
|
|
15
|
+
OrderedSetIndex,
|
|
16
|
+
build_async_ordered_set_index,
|
|
17
|
+
build_ordered_set_index,
|
|
18
|
+
)
|
|
19
|
+
from cachebind.indexes.registry import IndexRegistry
|
|
20
|
+
from cachebind.indexes.sets import (
|
|
21
|
+
AsyncSetIndex,
|
|
22
|
+
SetBase,
|
|
23
|
+
SetIndex,
|
|
24
|
+
build_async_set_index,
|
|
25
|
+
build_set_index,
|
|
26
|
+
)
|
|
27
|
+
from cachebind.indexes.tries import (
|
|
28
|
+
AsyncTrieIndex,
|
|
29
|
+
TrieBase,
|
|
30
|
+
TrieIndex,
|
|
31
|
+
build_async_trie_index,
|
|
32
|
+
build_trie_index,
|
|
33
|
+
)
|
|
34
|
+
|
|
35
|
+
__all__ = [
|
|
36
|
+
"AsyncEvictableIndex",
|
|
37
|
+
"AsyncKeyValueIndex",
|
|
38
|
+
"AsyncOrderedSetIndex",
|
|
39
|
+
"AsyncSetIndex",
|
|
40
|
+
"AsyncTrieIndex",
|
|
41
|
+
"EvictableIndex",
|
|
42
|
+
"Index",
|
|
43
|
+
"IndexRegistry",
|
|
44
|
+
"KeyValueBase",
|
|
45
|
+
"KeyValueIndex",
|
|
46
|
+
"OrderedSetBase",
|
|
47
|
+
"OrderedSetIndex",
|
|
48
|
+
"SetBase",
|
|
49
|
+
"SetIndex",
|
|
50
|
+
"TrieBase",
|
|
51
|
+
"TrieIndex",
|
|
52
|
+
"build_async_key_value_index",
|
|
53
|
+
"build_async_ordered_set_index",
|
|
54
|
+
"build_async_set_index",
|
|
55
|
+
"build_async_trie_index",
|
|
56
|
+
"build_key_value_index",
|
|
57
|
+
"build_ordered_set_index",
|
|
58
|
+
"build_set_index",
|
|
59
|
+
"build_trie_index",
|
|
60
|
+
"get_registry",
|
|
61
|
+
]
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
"""Breadcrumb helpers for index writes."""
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
def storage_identifier(value: object) -> str:
|
|
5
|
+
"""Turn a serialized storage value into the identifier string used in breadcrumbs."""
|
|
6
|
+
if isinstance(value, str):
|
|
7
|
+
return value
|
|
8
|
+
if isinstance(value, bytes):
|
|
9
|
+
return value.decode("utf-8")
|
|
10
|
+
return str(value)
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
"""Shared checks for building a registered index."""
|
|
2
|
+
|
|
3
|
+
import types
|
|
4
|
+
from typing import Any, Generic, Protocol, TypeVar, get_args, get_origin
|
|
5
|
+
|
|
6
|
+
from cachebind.indexes.base import get_registry
|
|
7
|
+
from cachebind.serializers.serializer import Serializer
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def check_key(key: str) -> None:
|
|
11
|
+
if not isinstance(key, str) or key == "":
|
|
12
|
+
raise TypeError(f"index key must be a non-empty str, got {key!r}")
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def instance_class(key: str, value: Any, *, label: str) -> type:
|
|
16
|
+
if isinstance(value, type):
|
|
17
|
+
raise TypeError(f"index {key!r}: {label} must be an instance, got class {value.__name__}")
|
|
18
|
+
return type(value)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def serializer_class(serializer: Any) -> type:
|
|
22
|
+
if isinstance(serializer, type):
|
|
23
|
+
return serializer
|
|
24
|
+
orig = getattr(serializer, "__orig_class__", None)
|
|
25
|
+
if orig is not None:
|
|
26
|
+
return orig
|
|
27
|
+
return type(serializer)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def serializer_types(key: str, serializer: Any) -> tuple[Any, Any]:
|
|
31
|
+
alias_args = get_args(serializer)
|
|
32
|
+
if alias_args and len(alias_args) == 2:
|
|
33
|
+
return alias_args
|
|
34
|
+
if not isinstance(serializer, type):
|
|
35
|
+
raise TypeError(
|
|
36
|
+
f"index {key!r}: serializer must be a class, got {type(serializer).__name__}"
|
|
37
|
+
)
|
|
38
|
+
args = protocol_args(serializer, Serializer)
|
|
39
|
+
if args is None or len(args) != 2:
|
|
40
|
+
raise TypeError(
|
|
41
|
+
f"index {key!r}: {serializer.__name__} does not declare "
|
|
42
|
+
"Serializer[ValueType, StorageType]"
|
|
43
|
+
)
|
|
44
|
+
return args
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def check_value_type(key: str, declared: Any, value_type: Any, *, label: str) -> None:
|
|
48
|
+
if value_matches(value_type, declared):
|
|
49
|
+
return
|
|
50
|
+
raise TypeError(
|
|
51
|
+
f"index {key!r}: {label} {declared!r} does not match "
|
|
52
|
+
f"serializer value type {value_type!r}"
|
|
53
|
+
)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def storage_client_type(key: str, storage: Any, protocol: type) -> type:
|
|
57
|
+
args = protocol_args(storage, protocol)
|
|
58
|
+
if args and isinstance(args[0], type):
|
|
59
|
+
return args[0]
|
|
60
|
+
name = storage.__name__ if isinstance(storage, type) else type(storage).__name__
|
|
61
|
+
raise TypeError(f"index {key!r}: {name} client type must be a class")
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def check_storage_type(key: str, serializer_storage: Any, storage_type: Any, storage: Any) -> None:
|
|
65
|
+
if serializer_storage != storage_type:
|
|
66
|
+
raise TypeError(
|
|
67
|
+
f"index {key!r}: serializer storage type {serializer_storage!r} "
|
|
68
|
+
f"does not match {storage.__name__} storage type {storage_type!r}"
|
|
69
|
+
)
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def value_matches(value_type: Any, declared: Any) -> bool:
|
|
73
|
+
if not isinstance(value_type, TypeVar):
|
|
74
|
+
return declared == value_type
|
|
75
|
+
constraints = value_type.__constraints__
|
|
76
|
+
if constraints:
|
|
77
|
+
return any(
|
|
78
|
+
declared == constraint or _is_subclass(declared, constraint)
|
|
79
|
+
for constraint in constraints
|
|
80
|
+
)
|
|
81
|
+
bound = value_type.__bound__
|
|
82
|
+
if bound is None:
|
|
83
|
+
return isinstance(declared, type)
|
|
84
|
+
return _is_subclass(declared, bound)
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def protocol_args(cls: Any, protocol: type) -> tuple[Any, ...] | None:
|
|
88
|
+
return _walk_protocol_args(cls, protocol, {}, ())
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def index_class(
|
|
92
|
+
key: str,
|
|
93
|
+
*,
|
|
94
|
+
serializer_instance: Any,
|
|
95
|
+
storage: Any,
|
|
96
|
+
base: type,
|
|
97
|
+
module: str,
|
|
98
|
+
attributes: dict[str, Any],
|
|
99
|
+
) -> Any:
|
|
100
|
+
suffix = "".join(char if char.isalnum() else "_" for char in key)
|
|
101
|
+
namespace: dict[str, Any] = {
|
|
102
|
+
"__module__": module,
|
|
103
|
+
"serializer": serializer_instance,
|
|
104
|
+
"key": key,
|
|
105
|
+
"storage": storage,
|
|
106
|
+
}
|
|
107
|
+
namespace.update(attributes)
|
|
108
|
+
type(f"{base.__name__}_{suffix}", (base,), namespace)
|
|
109
|
+
return get_registry(attributes["client_type"]).get(key)
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def _is_subclass(declared: Any, parent: Any) -> bool:
|
|
113
|
+
if not isinstance(declared, type):
|
|
114
|
+
return False
|
|
115
|
+
origin = get_origin(parent)
|
|
116
|
+
parent_type = origin if isinstance(origin, type) else parent
|
|
117
|
+
if not isinstance(parent_type, type):
|
|
118
|
+
return False
|
|
119
|
+
try:
|
|
120
|
+
return issubclass(declared, parent_type)
|
|
121
|
+
except TypeError:
|
|
122
|
+
return False
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
def _walk_protocol_args(
|
|
126
|
+
cls: Any,
|
|
127
|
+
protocol: type,
|
|
128
|
+
subst: dict[Any, Any],
|
|
129
|
+
stack: tuple[type, ...],
|
|
130
|
+
) -> tuple[Any, ...] | None:
|
|
131
|
+
if not isinstance(cls, type) or cls in stack or cls in {object, Protocol, Generic}:
|
|
132
|
+
return None
|
|
133
|
+
stack = (*stack, cls)
|
|
134
|
+
for base in types.get_original_bases(cls):
|
|
135
|
+
origin = get_origin(base)
|
|
136
|
+
if origin is None:
|
|
137
|
+
found = _walk_protocol_args(base, protocol, subst, stack)
|
|
138
|
+
if found is not None:
|
|
139
|
+
return found
|
|
140
|
+
continue
|
|
141
|
+
if origin is protocol:
|
|
142
|
+
return tuple(_substitute(arg, subst) for arg in get_args(base))
|
|
143
|
+
if not isinstance(origin, type):
|
|
144
|
+
continue
|
|
145
|
+
args = get_args(base)
|
|
146
|
+
params = getattr(origin, "__type_params__", ())
|
|
147
|
+
local = dict(subst)
|
|
148
|
+
if len(params) == len(args):
|
|
149
|
+
for param, arg in zip(params, args, strict=True):
|
|
150
|
+
local[param] = _substitute(arg, subst)
|
|
151
|
+
found = _walk_protocol_args(origin, protocol, local, stack)
|
|
152
|
+
if found is not None:
|
|
153
|
+
return found
|
|
154
|
+
return None
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
def _substitute(tp: Any, subst: dict[Any, Any]) -> Any:
|
|
158
|
+
if isinstance(tp, TypeVar):
|
|
159
|
+
return subst.get(tp, tp)
|
|
160
|
+
origin = get_origin(tp)
|
|
161
|
+
if origin is None:
|
|
162
|
+
return tp
|
|
163
|
+
args = get_args(tp)
|
|
164
|
+
substituted = tuple(_substitute(arg, subst) for arg in args)
|
|
165
|
+
if substituted == args:
|
|
166
|
+
return tp
|
|
167
|
+
try:
|
|
168
|
+
return origin[substituted]
|
|
169
|
+
except TypeError:
|
|
170
|
+
return tp
|
|
171
|
+
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
"""Choose the serializer for one index call."""
|
|
2
|
+
|
|
3
|
+
from collections.abc import Mapping
|
|
4
|
+
from typing import Any, cast
|
|
5
|
+
|
|
6
|
+
from cachebind.serializers.serializer import Serializer
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def resolve_serializer[ValueType, StorageType](
|
|
10
|
+
index_serializer: Serializer[ValueType, StorageType],
|
|
11
|
+
kwargs: Mapping[str, Any],
|
|
12
|
+
) -> Serializer[ValueType, StorageType]:
|
|
13
|
+
"""Return ``kwargs['serializer']`` when set, otherwise the index serializer."""
|
|
14
|
+
override = kwargs.get("serializer")
|
|
15
|
+
if override is None:
|
|
16
|
+
return index_serializer
|
|
17
|
+
return cast(Serializer[ValueType, StorageType], override)
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
"""Shared index registration."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import ClassVar, Self
|
|
6
|
+
|
|
7
|
+
from cachebind.indexes.registry import IndexRegistry
|
|
8
|
+
|
|
9
|
+
_registries: dict[type, IndexRegistry] = {}
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class Index:
|
|
13
|
+
"""Storage key and the registry that records an index.
|
|
14
|
+
|
|
15
|
+
Indexes that share a storage client type share one registry.
|
|
16
|
+
A subclass that defines ``key`` and ``client_type`` registers one instance.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
key: str
|
|
20
|
+
client_type: ClassVar[type]
|
|
21
|
+
|
|
22
|
+
def __init_subclass__(cls, **kwargs: object) -> None:
|
|
23
|
+
super().__init_subclass__(**kwargs)
|
|
24
|
+
if "key" not in cls.__dict__:
|
|
25
|
+
return
|
|
26
|
+
key = cls.__dict__["key"]
|
|
27
|
+
if not isinstance(key, str):
|
|
28
|
+
raise TypeError(f"{cls.__name__} key must be str, got {type(key).__name__}")
|
|
29
|
+
client_type = getattr(cls, "client_type", None)
|
|
30
|
+
if not isinstance(client_type, type):
|
|
31
|
+
raise TypeError(f"{cls.__name__} must declare client_type as a class")
|
|
32
|
+
registry = _registries.get(client_type)
|
|
33
|
+
if registry is None:
|
|
34
|
+
registry = IndexRegistry(client_type)
|
|
35
|
+
_registries[client_type] = registry
|
|
36
|
+
registry.set(key, cls())
|
|
37
|
+
|
|
38
|
+
def detach(self, key: str) -> Self:
|
|
39
|
+
"""Return an unregistered copy of this index bound to ``key``."""
|
|
40
|
+
clone = type(self)()
|
|
41
|
+
clone.key = key
|
|
42
|
+
return clone
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def get_registry(client_type: type) -> IndexRegistry:
|
|
46
|
+
"""Return the registry of indexes for this storage client type."""
|
|
47
|
+
try:
|
|
48
|
+
return _registries[client_type]
|
|
49
|
+
except KeyError:
|
|
50
|
+
name = client_type.__name__ if isinstance(client_type, type) else repr(client_type)
|
|
51
|
+
raise KeyError(f"no indexes registered for {name}") from None
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
"""Index eviction by tag identifier."""
|
|
2
|
+
|
|
3
|
+
from typing import Protocol, runtime_checkable
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
@runtime_checkable
|
|
7
|
+
class EvictableIndex[ClientType](Protocol):
|
|
8
|
+
"""Synchronous index that removes one entry by its tag identifier."""
|
|
9
|
+
|
|
10
|
+
def evict(self, client: ClientType, identifier: str) -> None:
|
|
11
|
+
"""Remove the entry for ``identifier``. A missing entry is not an error."""
|
|
12
|
+
...
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@runtime_checkable
|
|
16
|
+
class AsyncEvictableIndex[ClientType](Protocol):
|
|
17
|
+
"""Asynchronous index that removes one entry by its tag identifier."""
|
|
18
|
+
|
|
19
|
+
async def evict(self, client: ClientType, identifier: str) -> None:
|
|
20
|
+
"""Remove the entry for ``identifier``. A missing entry is not an error."""
|
|
21
|
+
...
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
"""Key-value indexes bind a model to key-value storage and register that binding by key."""
|
|
2
|
+
|
|
3
|
+
from cachebind.indexes.key_value.async_index import AsyncKeyValueIndex
|
|
4
|
+
from cachebind.indexes.key_value.base import KeyValueBase
|
|
5
|
+
from cachebind.indexes.key_value.builder import build_async_key_value_index, build_key_value_index
|
|
6
|
+
from cachebind.indexes.key_value.index import KeyValueIndex
|
|
7
|
+
|
|
8
|
+
__all__ = [
|
|
9
|
+
"AsyncKeyValueIndex",
|
|
10
|
+
"KeyValueBase",
|
|
11
|
+
"KeyValueIndex",
|
|
12
|
+
"build_async_key_value_index",
|
|
13
|
+
"build_key_value_index",
|
|
14
|
+
]
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
"""Asynchronous key-value index."""
|
|
2
|
+
|
|
3
|
+
from collections.abc import AsyncIterable, AsyncIterator, Hashable, Iterator, Mapping, Sequence
|
|
4
|
+
from typing import Self
|
|
5
|
+
|
|
6
|
+
from cachebind.indexes._serializer import resolve_serializer
|
|
7
|
+
from cachebind.indexes.key_value.base import KeyValueBase
|
|
8
|
+
from cachebind.serializers.serializer import Serializer
|
|
9
|
+
from cachebind.storage.key_value.async_storage import AsyncKeyValueStorage
|
|
10
|
+
|
|
11
|
+
BATCH = 100
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class AsyncKeyValueIndex[ClientType, IdType: Hashable, ModelType, StorageType](
|
|
15
|
+
KeyValueBase[ClientType, IdType, ModelType, StorageType]
|
|
16
|
+
):
|
|
17
|
+
"""Async key-value index: model binding, storage key, and the storage that persists it.
|
|
18
|
+
|
|
19
|
+
Reads deserialize and writes serialize. The identifier is stored as ``str(id)``.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
storage: AsyncKeyValueStorage[ClientType, str, StorageType]
|
|
23
|
+
|
|
24
|
+
async def get(
|
|
25
|
+
self,
|
|
26
|
+
client: ClientType,
|
|
27
|
+
id: IdType,
|
|
28
|
+
**kwargs,
|
|
29
|
+
) -> ModelType | None:
|
|
30
|
+
"""Return the cached model, or ``None`` when the id is missing."""
|
|
31
|
+
serializer = resolve_serializer(self.serializer, kwargs)
|
|
32
|
+
raw = await self.storage.get(client, self.key, str(id))
|
|
33
|
+
if raw is None:
|
|
34
|
+
return None
|
|
35
|
+
return serializer.deserialize(raw)
|
|
36
|
+
|
|
37
|
+
async def set(
|
|
38
|
+
self,
|
|
39
|
+
client: ClientType,
|
|
40
|
+
id: IdType,
|
|
41
|
+
value: ModelType,
|
|
42
|
+
*,
|
|
43
|
+
ttl: int | None = None,
|
|
44
|
+
**kwargs,
|
|
45
|
+
) -> str:
|
|
46
|
+
"""Store ``value`` under ``id``. Returns the breadcrumb for ``id``."""
|
|
47
|
+
serializer = resolve_serializer(self.serializer, kwargs)
|
|
48
|
+
field = str(id)
|
|
49
|
+
await self.storage.set(client, self.key, field, serializer.serialize(value), ttl=ttl)
|
|
50
|
+
return self.breadcrumbs.encode(self.key, field)
|
|
51
|
+
|
|
52
|
+
async def delete(self, client: ClientType, id: IdType) -> None:
|
|
53
|
+
"""Remove ``id``. A missing id is not an error."""
|
|
54
|
+
await self.storage.delete(client, self.key, str(id))
|
|
55
|
+
|
|
56
|
+
async def evict(self, client: ClientType, identifier: str) -> None:
|
|
57
|
+
"""Remove the entry for ``identifier``. A missing entry is not an error.
|
|
58
|
+
|
|
59
|
+
``identifier`` is the tag payload for one id (not the full encoded tag).
|
|
60
|
+
"""
|
|
61
|
+
await self.storage.delete(client, self.key, identifier)
|
|
62
|
+
|
|
63
|
+
async def mdelete(self, client: ClientType, ids: Sequence[IdType]) -> None:
|
|
64
|
+
"""Remove every id. Missing ids are not an error."""
|
|
65
|
+
if not ids:
|
|
66
|
+
return
|
|
67
|
+
await self.storage.mdelete(client, self.key, [str(id) for id in ids])
|
|
68
|
+
|
|
69
|
+
async def exists(self, client: ClientType, id: IdType) -> bool:
|
|
70
|
+
"""Return whether ``id`` is present."""
|
|
71
|
+
return await self.storage.exists(client, self.key, str(id))
|
|
72
|
+
|
|
73
|
+
async def mget(
|
|
74
|
+
self,
|
|
75
|
+
client: ClientType,
|
|
76
|
+
ids: Sequence[IdType],
|
|
77
|
+
**kwargs,
|
|
78
|
+
) -> list[ModelType | None]:
|
|
79
|
+
"""Return models in input order. Missing ids are ``None``."""
|
|
80
|
+
if not ids:
|
|
81
|
+
return []
|
|
82
|
+
serializer = resolve_serializer(self.serializer, kwargs)
|
|
83
|
+
raw_values = await self.storage.mget(client, self.key, [str(id) for id in ids])
|
|
84
|
+
present = [raw for raw in raw_values if raw is not None]
|
|
85
|
+
decoded = iter(serializer.mdeserialize(present))
|
|
86
|
+
return [None if raw is None else next(decoded) for raw in raw_values]
|
|
87
|
+
|
|
88
|
+
async def mset(
|
|
89
|
+
self,
|
|
90
|
+
client: ClientType,
|
|
91
|
+
items: Mapping[IdType, ModelType],
|
|
92
|
+
*,
|
|
93
|
+
ttl: int | None = None,
|
|
94
|
+
**kwargs,
|
|
95
|
+
) -> list[str]:
|
|
96
|
+
"""Store every item. ``ttl`` applies to each id. Returns one breadcrumb per item."""
|
|
97
|
+
if not items:
|
|
98
|
+
return []
|
|
99
|
+
serializer = resolve_serializer(self.serializer, kwargs)
|
|
100
|
+
fields = [str(id) for id in items]
|
|
101
|
+
values = serializer.mserialize(list(items.values()))
|
|
102
|
+
mapping = dict(zip(fields, values, strict=True))
|
|
103
|
+
await self.storage.mset(client, self.key, mapping, ttl=ttl)
|
|
104
|
+
return [self.breadcrumbs.encode(self.key, field) for field in fields]
|
|
105
|
+
|
|
106
|
+
async def swap(self, client: ClientType) -> Self:
|
|
107
|
+
"""Rename this index aside and return an unregistered index for that data."""
|
|
108
|
+
return self.detach(await self.storage.swap(client, self.key))
|
|
109
|
+
|
|
110
|
+
async def drop(self, client: ClientType) -> None:
|
|
111
|
+
"""Delete the key this index is bound to. A missing key is not an error."""
|
|
112
|
+
await self.storage.drop(client, self.key)
|
|
113
|
+
|
|
114
|
+
async def iter(
|
|
115
|
+
self,
|
|
116
|
+
client: ClientType,
|
|
117
|
+
**kwargs,
|
|
118
|
+
) -> AsyncIterator[tuple[str, ModelType]]:
|
|
119
|
+
"""Yield each stored id and model under this index key."""
|
|
120
|
+
serializer = resolve_serializer(self.serializer, kwargs)
|
|
121
|
+
async for pair in async_pairs(self.storage.iter(client, self.key), serializer):
|
|
122
|
+
yield pair
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
async def async_pairs[StorageType, ValueType](
|
|
126
|
+
raw: AsyncIterable[tuple[str, StorageType]], serializer: Serializer[ValueType, StorageType]
|
|
127
|
+
) -> AsyncIterator[tuple[str, ValueType]]:
|
|
128
|
+
"""Yield stored ids and deserialized values, one ``mdeserialize`` per batch."""
|
|
129
|
+
batch: list[tuple[str, StorageType]] = []
|
|
130
|
+
async for item in raw:
|
|
131
|
+
batch.append(item)
|
|
132
|
+
if len(batch) == BATCH:
|
|
133
|
+
for decoded in _pairs(batch, serializer):
|
|
134
|
+
yield decoded
|
|
135
|
+
batch = []
|
|
136
|
+
if batch:
|
|
137
|
+
for decoded in _pairs(batch, serializer):
|
|
138
|
+
yield decoded
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def _pairs[StorageType, ValueType](
|
|
142
|
+
batch: list[tuple[str, StorageType]], serializer: Serializer[ValueType, StorageType]
|
|
143
|
+
) -> Iterator[tuple[str, ValueType]]:
|
|
144
|
+
decoded = serializer.mdeserialize([value for _field, value in batch])
|
|
145
|
+
return zip((field for field, _value in batch), decoded, strict=True)
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
"""Shared key-value index attributes."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import Hashable
|
|
6
|
+
|
|
7
|
+
from cachebind.indexes.base import Index
|
|
8
|
+
from cachebind.serializers.serializer import Serializer
|
|
9
|
+
from cachebind.tagging import Breadcrumbs, NoopBreadcrumbs
|
|
10
|
+
from cachebind.storage.key_value.async_storage import AsyncKeyValueStorage
|
|
11
|
+
from cachebind.storage.key_value.storage import KeyValueStorage
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class KeyValueBase[ClientType, IdType: Hashable, ModelType, StorageType](Index):
|
|
15
|
+
"""Identifier, model, serializer, storage key, and storage for a key-value index.
|
|
16
|
+
|
|
17
|
+
``ModelType`` is unconstrained: a builtin such as ``int`` or any class.
|
|
18
|
+
``key`` names that model in storage. For a hash storage it is the hash name.
|
|
19
|
+
``storage`` is the key-value storage instance. Fields are stored as ``str``.
|
|
20
|
+
Each call receives the storage client.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
identifier: type[IdType]
|
|
24
|
+
model: type[ModelType]
|
|
25
|
+
breadcrumbs: Breadcrumbs = NoopBreadcrumbs()
|
|
26
|
+
serializer: Serializer[ModelType, StorageType]
|
|
27
|
+
storage: (
|
|
28
|
+
KeyValueStorage[ClientType, str, StorageType]
|
|
29
|
+
| AsyncKeyValueStorage[ClientType, str, StorageType]
|
|
30
|
+
)
|