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.
Files changed (81) hide show
  1. cachebind/__init__.py +121 -0
  2. cachebind/indexes/__init__.py +61 -0
  3. cachebind/indexes/_breadcrumb.py +10 -0
  4. cachebind/indexes/_builder.py +171 -0
  5. cachebind/indexes/_serializer.py +17 -0
  6. cachebind/indexes/base.py +51 -0
  7. cachebind/indexes/evict.py +21 -0
  8. cachebind/indexes/key_value/__init__.py +14 -0
  9. cachebind/indexes/key_value/async_index.py +145 -0
  10. cachebind/indexes/key_value/base.py +30 -0
  11. cachebind/indexes/key_value/builder.py +170 -0
  12. cachebind/indexes/key_value/index.py +142 -0
  13. cachebind/indexes/ordered_sets/__init__.py +17 -0
  14. cachebind/indexes/ordered_sets/async_index.py +221 -0
  15. cachebind/indexes/ordered_sets/base.py +38 -0
  16. cachebind/indexes/ordered_sets/builder.py +146 -0
  17. cachebind/indexes/ordered_sets/index.py +218 -0
  18. cachebind/indexes/registry.py +38 -0
  19. cachebind/indexes/sets/__init__.py +14 -0
  20. cachebind/indexes/sets/async_index.py +124 -0
  21. cachebind/indexes/sets/base.py +24 -0
  22. cachebind/indexes/sets/builder.py +146 -0
  23. cachebind/indexes/sets/index.py +121 -0
  24. cachebind/indexes/tries/__init__.py +14 -0
  25. cachebind/indexes/tries/async_index.py +113 -0
  26. cachebind/indexes/tries/base.py +25 -0
  27. cachebind/indexes/tries/builder.py +141 -0
  28. cachebind/indexes/tries/index.py +113 -0
  29. cachebind/serializers/__init__.py +29 -0
  30. cachebind/serializers/bool_serializer.py +21 -0
  31. cachebind/serializers/dataclass_serializer.py +102 -0
  32. cachebind/serializers/datetime_serializer.py +22 -0
  33. cachebind/serializers/dict_serializer.py +29 -0
  34. cachebind/serializers/float_serializer.py +18 -0
  35. cachebind/serializers/int_serializer.py +20 -0
  36. cachebind/serializers/noop_serializer.py +19 -0
  37. cachebind/serializers/pydantic_serializer.py +29 -0
  38. cachebind/serializers/serializer.py +24 -0
  39. cachebind/serializers/str_serializer.py +13 -0
  40. cachebind/serializers/uuid_serializer.py +22 -0
  41. cachebind/storage/__init__.py +67 -0
  42. cachebind/storage/_redis.py +80 -0
  43. cachebind/storage/key_value/__init__.py +37 -0
  44. cachebind/storage/key_value/async_redis_hash_storage.py +73 -0
  45. cachebind/storage/key_value/async_redis_string_storage.py +72 -0
  46. cachebind/storage/key_value/async_storage.py +76 -0
  47. cachebind/storage/key_value/redis_hash_storage.py +73 -0
  48. cachebind/storage/key_value/redis_string_storage.py +72 -0
  49. cachebind/storage/key_value/storage.py +74 -0
  50. cachebind/storage/ordered_sets/__init__.py +29 -0
  51. cachebind/storage/ordered_sets/_values.py +60 -0
  52. cachebind/storage/ordered_sets/async_redis_ordered_set_storage.py +91 -0
  53. cachebind/storage/ordered_sets/async_storage.py +89 -0
  54. cachebind/storage/ordered_sets/redis_ordered_set_storage.py +88 -0
  55. cachebind/storage/ordered_sets/storage.py +85 -0
  56. cachebind/storage/sets/__init__.py +27 -0
  57. cachebind/storage/sets/async_redis_set_storage.py +54 -0
  58. cachebind/storage/sets/async_storage.py +49 -0
  59. cachebind/storage/sets/redis_set_storage.py +52 -0
  60. cachebind/storage/sets/storage.py +49 -0
  61. cachebind/storage/tries/__init__.py +27 -0
  62. cachebind/storage/tries/_reply.py +20 -0
  63. cachebind/storage/tries/_values.py +36 -0
  64. cachebind/storage/tries/async_redis_trie_storage.py +81 -0
  65. cachebind/storage/tries/async_storage.py +78 -0
  66. cachebind/storage/tries/redis_trie_storage.py +79 -0
  67. cachebind/storage/tries/storage.py +78 -0
  68. cachebind/tagging/__init__.py +19 -0
  69. cachebind/tagging/breadcrumbs/__init__.py +11 -0
  70. cachebind/tagging/breadcrumbs/colon_breadcrumbs.py +20 -0
  71. cachebind/tagging/breadcrumbs/noop_breadcrumbs.py +15 -0
  72. cachebind/tagging/breadcrumbs/protocol.py +15 -0
  73. cachebind/tagging/tag_keeper/__init__.py +12 -0
  74. cachebind/tagging/tag_keeper/_keys.py +10 -0
  75. cachebind/tagging/tag_keeper/async_set_tag_keeper.py +47 -0
  76. cachebind/tagging/tag_keeper/protocol.py +37 -0
  77. cachebind/tagging/tag_keeper/set_tag_keeper.py +47 -0
  78. cachebind-1.0.0.dist-info/METADATA +171 -0
  79. cachebind-1.0.0.dist-info/RECORD +81 -0
  80. cachebind-1.0.0.dist-info/WHEEL +4 -0
  81. 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
+ )