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
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
"""Build a registered set index from its parts and check that those parts agree."""
|
|
2
|
+
|
|
3
|
+
from collections.abc import Hashable
|
|
4
|
+
from typing import Any, cast
|
|
5
|
+
|
|
6
|
+
from cachebind.indexes._builder import (
|
|
7
|
+
check_key,
|
|
8
|
+
check_storage_type,
|
|
9
|
+
check_value_type,
|
|
10
|
+
index_class,
|
|
11
|
+
instance_class,
|
|
12
|
+
protocol_args,
|
|
13
|
+
serializer_class,
|
|
14
|
+
serializer_types,
|
|
15
|
+
storage_client_type,
|
|
16
|
+
)
|
|
17
|
+
from cachebind.indexes.sets.async_index import AsyncSetIndex
|
|
18
|
+
from cachebind.indexes.sets.index import SetIndex
|
|
19
|
+
from cachebind.serializers.serializer import Serializer
|
|
20
|
+
from cachebind.tagging import Breadcrumbs, ColonBreadcrumbs, NoopBreadcrumbs
|
|
21
|
+
from cachebind.storage.sets.async_storage import AsyncSetStorage
|
|
22
|
+
from cachebind.storage.sets.storage import SetStorage
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def build_set_index[
|
|
26
|
+
ClientType,
|
|
27
|
+
MemberType,
|
|
28
|
+
StorageType: Hashable,
|
|
29
|
+
Storage: SetStorage[ClientType, StorageType],
|
|
30
|
+
](
|
|
31
|
+
key: str,
|
|
32
|
+
*,
|
|
33
|
+
member_type: type[MemberType],
|
|
34
|
+
serializer: Serializer[MemberType, StorageType],
|
|
35
|
+
storage: Storage,
|
|
36
|
+
breadcrumbs: Breadcrumbs | None = None,
|
|
37
|
+
) -> SetIndex[ClientType, MemberType, StorageType]:
|
|
38
|
+
"""Register a sync set index whose member, serializer, and storage types agree.
|
|
39
|
+
|
|
40
|
+
``serializer`` and ``storage`` are instances. The returned index is registered
|
|
41
|
+
and ready to use. Pass the storage client to each index method.
|
|
42
|
+
"""
|
|
43
|
+
return cast(
|
|
44
|
+
SetIndex[ClientType, MemberType, StorageType],
|
|
45
|
+
_build(
|
|
46
|
+
key,
|
|
47
|
+
member_type=member_type,
|
|
48
|
+
serializer=serializer,
|
|
49
|
+
storage=storage,
|
|
50
|
+
breadcrumbs=breadcrumbs,
|
|
51
|
+
base=SetIndex,
|
|
52
|
+
protocol=SetStorage,
|
|
53
|
+
other=AsyncSetStorage,
|
|
54
|
+
),
|
|
55
|
+
)
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def build_async_set_index[
|
|
59
|
+
ClientType,
|
|
60
|
+
MemberType,
|
|
61
|
+
StorageType: Hashable,
|
|
62
|
+
Storage: AsyncSetStorage[ClientType, StorageType],
|
|
63
|
+
](
|
|
64
|
+
key: str,
|
|
65
|
+
*,
|
|
66
|
+
member_type: type[MemberType],
|
|
67
|
+
serializer: Serializer[MemberType, StorageType],
|
|
68
|
+
storage: Storage,
|
|
69
|
+
breadcrumbs: Breadcrumbs | None = None,
|
|
70
|
+
) -> AsyncSetIndex[ClientType, MemberType, StorageType]:
|
|
71
|
+
"""Register an async set index whose member, serializer, and storage types agree.
|
|
72
|
+
|
|
73
|
+
``serializer`` and ``storage`` are instances. The returned index is registered
|
|
74
|
+
and ready to use. Pass the storage client to each index method.
|
|
75
|
+
"""
|
|
76
|
+
return cast(
|
|
77
|
+
AsyncSetIndex[ClientType, MemberType, StorageType],
|
|
78
|
+
_build(
|
|
79
|
+
key,
|
|
80
|
+
member_type=member_type,
|
|
81
|
+
serializer=serializer,
|
|
82
|
+
storage=storage,
|
|
83
|
+
breadcrumbs=breadcrumbs,
|
|
84
|
+
base=AsyncSetIndex,
|
|
85
|
+
protocol=AsyncSetStorage,
|
|
86
|
+
other=SetStorage,
|
|
87
|
+
),
|
|
88
|
+
)
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def _build(
|
|
92
|
+
key: str,
|
|
93
|
+
*,
|
|
94
|
+
member_type: Any,
|
|
95
|
+
serializer: Any,
|
|
96
|
+
storage: Any,
|
|
97
|
+
breadcrumbs: Breadcrumbs | None,
|
|
98
|
+
base: type[SetIndex[Any, Any, Any]] | type[AsyncSetIndex[Any, Any, Any]],
|
|
99
|
+
protocol: type[SetStorage[Any, Any]] | type[AsyncSetStorage[Any, Any]],
|
|
100
|
+
other: type[SetStorage[Any, Any]] | type[AsyncSetStorage[Any, Any]],
|
|
101
|
+
) -> Any:
|
|
102
|
+
check_key(key)
|
|
103
|
+
instance_class(key, serializer, label="serializer")
|
|
104
|
+
value_type, serializer_storage = serializer_types(key, serializer_class(serializer))
|
|
105
|
+
check_value_type(key, member_type, value_type, label="member type")
|
|
106
|
+
storage_cls = instance_class(key, storage, label="storage")
|
|
107
|
+
storage_type = _storage_type(key, storage_cls, protocol, other)
|
|
108
|
+
check_storage_type(key, serializer_storage, storage_type, storage_cls)
|
|
109
|
+
client_type = storage_client_type(key, storage_cls, protocol)
|
|
110
|
+
if breadcrumbs is None:
|
|
111
|
+
breadcrumbs = ColonBreadcrumbs()
|
|
112
|
+
else:
|
|
113
|
+
instance_class(key, breadcrumbs, label="breadcrumbs")
|
|
114
|
+
return index_class(
|
|
115
|
+
key,
|
|
116
|
+
serializer_instance=serializer,
|
|
117
|
+
storage=storage,
|
|
118
|
+
base=base,
|
|
119
|
+
module=__name__,
|
|
120
|
+
attributes={"member": member_type, "client_type": client_type, "breadcrumbs": breadcrumbs},
|
|
121
|
+
)
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def _storage_type(
|
|
125
|
+
key: str,
|
|
126
|
+
storage: type,
|
|
127
|
+
protocol: type,
|
|
128
|
+
other: type,
|
|
129
|
+
) -> Any:
|
|
130
|
+
args = protocol_args(storage, protocol)
|
|
131
|
+
if args is None or len(args) != 2:
|
|
132
|
+
if protocol_args(storage, other) is not None:
|
|
133
|
+
if protocol is SetStorage:
|
|
134
|
+
raise TypeError(
|
|
135
|
+
f"index {key!r}: {storage.__name__} is asynchronous; "
|
|
136
|
+
"build_set_index requires SetStorage"
|
|
137
|
+
)
|
|
138
|
+
raise TypeError(
|
|
139
|
+
f"index {key!r}: {storage.__name__} is synchronous; "
|
|
140
|
+
"build_async_set_index requires AsyncSetStorage"
|
|
141
|
+
)
|
|
142
|
+
raise TypeError(
|
|
143
|
+
f"index {key!r}: {storage.__name__} does not declare "
|
|
144
|
+
f"{protocol.__name__}[ClientType, MemberType]"
|
|
145
|
+
)
|
|
146
|
+
return args[1]
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
"""Synchronous set index."""
|
|
2
|
+
|
|
3
|
+
from collections.abc import Hashable, Iterable, Iterator, Sequence
|
|
4
|
+
from typing import Self, cast
|
|
5
|
+
|
|
6
|
+
from cachebind.indexes._serializer import resolve_serializer
|
|
7
|
+
from cachebind.indexes._breadcrumb import storage_identifier
|
|
8
|
+
from cachebind.indexes.sets.base import SetBase
|
|
9
|
+
from cachebind.serializers.serializer import Serializer
|
|
10
|
+
from cachebind.storage.sets.storage import SetStorage
|
|
11
|
+
|
|
12
|
+
BATCH = 100
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class SetIndex[ClientType, MemberType, StorageType: Hashable](
|
|
16
|
+
SetBase[ClientType, MemberType, StorageType]
|
|
17
|
+
):
|
|
18
|
+
"""Sync set index: member binding, storage key, and the storage that persists it.
|
|
19
|
+
|
|
20
|
+
Writes serialize the member. ``contains`` serializes the lookup value.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
storage: SetStorage[ClientType, StorageType]
|
|
24
|
+
|
|
25
|
+
def add(
|
|
26
|
+
self,
|
|
27
|
+
client: ClientType,
|
|
28
|
+
member: MemberType,
|
|
29
|
+
**kwargs,
|
|
30
|
+
) -> str:
|
|
31
|
+
"""Add ``member``. A member that is already present is not an error."""
|
|
32
|
+
serializer = resolve_serializer(self.serializer, kwargs)
|
|
33
|
+
stored = serializer.serialize(member)
|
|
34
|
+
self.storage.add(client, self.key, stored)
|
|
35
|
+
return self.breadcrumbs.encode(self.key, storage_identifier(stored))
|
|
36
|
+
|
|
37
|
+
def madd(
|
|
38
|
+
self,
|
|
39
|
+
client: ClientType,
|
|
40
|
+
members: Sequence[MemberType],
|
|
41
|
+
**kwargs,
|
|
42
|
+
) -> list[str]:
|
|
43
|
+
"""Add every member."""
|
|
44
|
+
if not members:
|
|
45
|
+
return []
|
|
46
|
+
serializer = resolve_serializer(self.serializer, kwargs)
|
|
47
|
+
stored = serializer.mserialize(members)
|
|
48
|
+
self.storage.madd(client, self.key, stored)
|
|
49
|
+
return [
|
|
50
|
+
self.breadcrumbs.encode(self.key, storage_identifier(value)) for value in stored
|
|
51
|
+
]
|
|
52
|
+
|
|
53
|
+
def remove(
|
|
54
|
+
self,
|
|
55
|
+
client: ClientType,
|
|
56
|
+
member: MemberType,
|
|
57
|
+
**kwargs,
|
|
58
|
+
) -> None:
|
|
59
|
+
"""Remove ``member``. A missing member is not an error."""
|
|
60
|
+
serializer = resolve_serializer(self.serializer, kwargs)
|
|
61
|
+
self.storage.remove(client, self.key, serializer.serialize(member))
|
|
62
|
+
|
|
63
|
+
def evict(self, client: ClientType, identifier: str) -> None:
|
|
64
|
+
"""Remove the entry for ``identifier``. A missing entry is not an error.
|
|
65
|
+
|
|
66
|
+
``identifier`` is the tag payload for one member (not the full encoded tag).
|
|
67
|
+
"""
|
|
68
|
+
self.storage.remove(client, self.key, cast(StorageType, identifier))
|
|
69
|
+
|
|
70
|
+
def mremove(
|
|
71
|
+
self,
|
|
72
|
+
client: ClientType,
|
|
73
|
+
members: Sequence[MemberType],
|
|
74
|
+
**kwargs,
|
|
75
|
+
) -> None:
|
|
76
|
+
"""Remove every member. Missing members are not an error."""
|
|
77
|
+
if not members:
|
|
78
|
+
return
|
|
79
|
+
serializer = resolve_serializer(self.serializer, kwargs)
|
|
80
|
+
self.storage.mremove(client, self.key, serializer.mserialize(members))
|
|
81
|
+
|
|
82
|
+
def contains(
|
|
83
|
+
self,
|
|
84
|
+
client: ClientType,
|
|
85
|
+
member: MemberType,
|
|
86
|
+
**kwargs,
|
|
87
|
+
) -> bool:
|
|
88
|
+
"""Return whether ``member`` is in the set."""
|
|
89
|
+
serializer = resolve_serializer(self.serializer, kwargs)
|
|
90
|
+
return self.storage.contains(client, self.key, serializer.serialize(member))
|
|
91
|
+
|
|
92
|
+
def swap(self, client: ClientType) -> Self:
|
|
93
|
+
"""Rename this index aside and return an unregistered index for that data."""
|
|
94
|
+
return self.detach(self.storage.swap(client, self.key))
|
|
95
|
+
|
|
96
|
+
def drop(self, client: ClientType) -> None:
|
|
97
|
+
"""Delete the key this index is bound to. A missing key is not an error."""
|
|
98
|
+
self.storage.drop(client, self.key)
|
|
99
|
+
|
|
100
|
+
def iter(
|
|
101
|
+
self,
|
|
102
|
+
client: ClientType,
|
|
103
|
+
**kwargs,
|
|
104
|
+
) -> Iterator[MemberType]:
|
|
105
|
+
"""Yield each member stored under this index key."""
|
|
106
|
+
serializer = resolve_serializer(self.serializer, kwargs)
|
|
107
|
+
return values(self.storage.iter(client, self.key), serializer)
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def values[StorageType, ValueType](
|
|
111
|
+
raw: Iterable[StorageType], serializer: Serializer[ValueType, StorageType]
|
|
112
|
+
) -> Iterator[ValueType]:
|
|
113
|
+
"""Yield deserialized values, calling ``mdeserialize`` once per batch."""
|
|
114
|
+
batch: list[StorageType] = []
|
|
115
|
+
for value in raw:
|
|
116
|
+
batch.append(value)
|
|
117
|
+
if len(batch) == BATCH:
|
|
118
|
+
yield from serializer.mdeserialize(batch)
|
|
119
|
+
batch = []
|
|
120
|
+
if batch:
|
|
121
|
+
yield from serializer.mdeserialize(batch)
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
"""Trie indexes bind a member to trie storage and register that binding by key."""
|
|
2
|
+
|
|
3
|
+
from cachebind.indexes.tries.async_index import AsyncTrieIndex
|
|
4
|
+
from cachebind.indexes.tries.base import TrieBase
|
|
5
|
+
from cachebind.indexes.tries.builder import build_async_trie_index, build_trie_index
|
|
6
|
+
from cachebind.indexes.tries.index import TrieIndex
|
|
7
|
+
|
|
8
|
+
__all__ = [
|
|
9
|
+
"AsyncTrieIndex",
|
|
10
|
+
"TrieBase",
|
|
11
|
+
"TrieIndex",
|
|
12
|
+
"build_async_trie_index",
|
|
13
|
+
"build_trie_index",
|
|
14
|
+
]
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
"""Asynchronous trie index."""
|
|
2
|
+
|
|
3
|
+
from collections.abc import Hashable, Sequence
|
|
4
|
+
from typing import Self
|
|
5
|
+
|
|
6
|
+
from cachebind.indexes._serializer import resolve_serializer
|
|
7
|
+
from cachebind.indexes.tries.base import TrieBase
|
|
8
|
+
from cachebind.storage.tries._values import check_limit
|
|
9
|
+
from cachebind.storage.tries.async_storage import AsyncTrieStorage
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class AsyncTrieIndex[ClientType, MemberType, StorageType: Hashable](
|
|
13
|
+
TrieBase[ClientType, MemberType, StorageType]
|
|
14
|
+
):
|
|
15
|
+
"""Async trie index: member binding, storage key, and the storage that persists it.
|
|
16
|
+
|
|
17
|
+
The suggestion string and the score are stored as given. The member is the payload:
|
|
18
|
+
writes serialize it, and ``search`` deserializes the payloads in rank order.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
storage: AsyncTrieStorage[ClientType, StorageType]
|
|
22
|
+
|
|
23
|
+
async def add(
|
|
24
|
+
self,
|
|
25
|
+
client: ClientType,
|
|
26
|
+
string: str,
|
|
27
|
+
member: MemberType,
|
|
28
|
+
score: float,
|
|
29
|
+
*,
|
|
30
|
+
increment: bool = False,
|
|
31
|
+
**kwargs,
|
|
32
|
+
) -> str:
|
|
33
|
+
"""Add ``string`` with ``score`` and ``member`` as its payload.
|
|
34
|
+
|
|
35
|
+
A string that is already present gets the new score and payload.
|
|
36
|
+
``increment=True`` adds ``score`` to the stored score instead of replacing it.
|
|
37
|
+
"""
|
|
38
|
+
serializer = resolve_serializer(self.serializer, kwargs)
|
|
39
|
+
await self.storage.add(
|
|
40
|
+
client,
|
|
41
|
+
self.key,
|
|
42
|
+
string,
|
|
43
|
+
score,
|
|
44
|
+
serializer.serialize(member),
|
|
45
|
+
increment=increment,
|
|
46
|
+
)
|
|
47
|
+
return self.breadcrumbs.encode(self.key, "")
|
|
48
|
+
|
|
49
|
+
async def madd(
|
|
50
|
+
self,
|
|
51
|
+
client: ClientType,
|
|
52
|
+
entries: Sequence[tuple[str, MemberType, float]],
|
|
53
|
+
*,
|
|
54
|
+
increment: bool = False,
|
|
55
|
+
**kwargs,
|
|
56
|
+
) -> list[str]:
|
|
57
|
+
"""Add every suggestion. A repeated string keeps the last score and payload."""
|
|
58
|
+
if not entries:
|
|
59
|
+
return []
|
|
60
|
+
serializer = resolve_serializer(self.serializer, kwargs)
|
|
61
|
+
serialized = serializer.mserialize([member for _string, member, _score in entries])
|
|
62
|
+
stored = [
|
|
63
|
+
(string, score, payload)
|
|
64
|
+
for (string, _member, score), payload in zip(entries, serialized, strict=True)
|
|
65
|
+
]
|
|
66
|
+
await self.storage.madd(client, self.key, stored, increment=increment)
|
|
67
|
+
crumb = self.breadcrumbs.encode(self.key, "")
|
|
68
|
+
return [crumb] * len(entries)
|
|
69
|
+
|
|
70
|
+
async def remove(self, client: ClientType, string: str) -> None:
|
|
71
|
+
"""Remove the suggestion ``string``. A missing string is not an error."""
|
|
72
|
+
await self.storage.remove(client, self.key, string)
|
|
73
|
+
|
|
74
|
+
async def evict(self, client: ClientType, identifier: str) -> None:
|
|
75
|
+
"""Not supported: trie tags do not identify one entry."""
|
|
76
|
+
raise NotImplementedError("evict is not supported for trie indexes")
|
|
77
|
+
|
|
78
|
+
async def mremove(self, client: ClientType, strings: Sequence[str]) -> None:
|
|
79
|
+
"""Remove every suggestion string. Missing strings are not an error."""
|
|
80
|
+
if not strings:
|
|
81
|
+
return
|
|
82
|
+
await self.storage.mremove(client, self.key, strings)
|
|
83
|
+
|
|
84
|
+
async def search(
|
|
85
|
+
self,
|
|
86
|
+
client: ClientType,
|
|
87
|
+
prefix: str,
|
|
88
|
+
*,
|
|
89
|
+
fuzzy: bool = False,
|
|
90
|
+
limit: int = 10,
|
|
91
|
+
**kwargs,
|
|
92
|
+
) -> list[MemberType]:
|
|
93
|
+
"""Return members whose suggestion string matches ``prefix``, in rank order.
|
|
94
|
+
|
|
95
|
+
``limit`` is the maximum number of members. ``fuzzy`` allows a one-edit prefix.
|
|
96
|
+
Members are deserialized from the stored payloads.
|
|
97
|
+
"""
|
|
98
|
+
check_limit(limit)
|
|
99
|
+
serializer = resolve_serializer(self.serializer, kwargs)
|
|
100
|
+
raw = await self.storage.search(client, self.key, prefix, fuzzy=fuzzy, limit=limit)
|
|
101
|
+
return serializer.mdeserialize(raw)
|
|
102
|
+
|
|
103
|
+
async def length(self, client: ClientType) -> int:
|
|
104
|
+
"""Return the number of suggestion strings in the trie."""
|
|
105
|
+
return await self.storage.length(client, self.key)
|
|
106
|
+
|
|
107
|
+
async def swap(self, client: ClientType) -> Self:
|
|
108
|
+
"""Rename this index aside and return an unregistered index for that data."""
|
|
109
|
+
return self.detach(await self.storage.swap(client, self.key))
|
|
110
|
+
|
|
111
|
+
async def drop(self, client: ClientType) -> None:
|
|
112
|
+
"""Delete the key this index is bound to. A missing key is not an error."""
|
|
113
|
+
await self.storage.drop(client, self.key)
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
"""Shared trie 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.tries.async_storage import AsyncTrieStorage
|
|
11
|
+
from cachebind.storage.tries.storage import TrieStorage
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class TrieBase[ClientType, MemberType, StorageType: Hashable](Index):
|
|
15
|
+
"""Member, serializer, storage key, and storage for a trie index.
|
|
16
|
+
|
|
17
|
+
``key`` is the trie name. ``storage`` stores suggestion strings, scores, and payloads.
|
|
18
|
+
The serializer converts a member to that payload and back.
|
|
19
|
+
Each call receives the storage client.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
member: type[MemberType]
|
|
23
|
+
breadcrumbs: Breadcrumbs = NoopBreadcrumbs()
|
|
24
|
+
serializer: Serializer[MemberType, StorageType]
|
|
25
|
+
storage: TrieStorage[ClientType, StorageType] | AsyncTrieStorage[ClientType, StorageType]
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
"""Build a registered trie index from its parts and check that those parts agree."""
|
|
2
|
+
|
|
3
|
+
from collections.abc import Hashable
|
|
4
|
+
from typing import Any, cast
|
|
5
|
+
|
|
6
|
+
from cachebind.indexes._builder import (
|
|
7
|
+
check_key,
|
|
8
|
+
check_storage_type,
|
|
9
|
+
check_value_type,
|
|
10
|
+
index_class,
|
|
11
|
+
instance_class,
|
|
12
|
+
protocol_args,
|
|
13
|
+
serializer_class,
|
|
14
|
+
serializer_types,
|
|
15
|
+
storage_client_type,
|
|
16
|
+
)
|
|
17
|
+
from cachebind.indexes.tries.async_index import AsyncTrieIndex
|
|
18
|
+
from cachebind.indexes.tries.index import TrieIndex
|
|
19
|
+
from cachebind.serializers.serializer import Serializer
|
|
20
|
+
from cachebind.tagging import NoopBreadcrumbs
|
|
21
|
+
from cachebind.storage.tries.async_storage import AsyncTrieStorage
|
|
22
|
+
from cachebind.storage.tries.storage import TrieStorage
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def build_trie_index[
|
|
26
|
+
ClientType,
|
|
27
|
+
MemberType,
|
|
28
|
+
StorageType: Hashable,
|
|
29
|
+
Storage: TrieStorage[ClientType, StorageType],
|
|
30
|
+
](
|
|
31
|
+
key: str,
|
|
32
|
+
*,
|
|
33
|
+
member_type: type[MemberType],
|
|
34
|
+
serializer: Serializer[MemberType, StorageType],
|
|
35
|
+
storage: Storage,
|
|
36
|
+
) -> TrieIndex[ClientType, MemberType, StorageType]:
|
|
37
|
+
"""Register a sync trie index whose member, serializer, and storage types agree.
|
|
38
|
+
|
|
39
|
+
``serializer`` and ``storage`` are instances. The returned index is registered
|
|
40
|
+
and ready to use. Pass the storage client to each index method.
|
|
41
|
+
"""
|
|
42
|
+
return cast(
|
|
43
|
+
TrieIndex[ClientType, MemberType, StorageType],
|
|
44
|
+
_build(
|
|
45
|
+
key,
|
|
46
|
+
member_type=member_type,
|
|
47
|
+
serializer=serializer,
|
|
48
|
+
storage=storage,
|
|
49
|
+
base=TrieIndex,
|
|
50
|
+
protocol=TrieStorage,
|
|
51
|
+
other=AsyncTrieStorage,
|
|
52
|
+
),
|
|
53
|
+
)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def build_async_trie_index[
|
|
57
|
+
ClientType,
|
|
58
|
+
MemberType,
|
|
59
|
+
StorageType: Hashable,
|
|
60
|
+
Storage: AsyncTrieStorage[ClientType, StorageType],
|
|
61
|
+
](
|
|
62
|
+
key: str,
|
|
63
|
+
*,
|
|
64
|
+
member_type: type[MemberType],
|
|
65
|
+
serializer: Serializer[MemberType, StorageType],
|
|
66
|
+
storage: Storage,
|
|
67
|
+
) -> AsyncTrieIndex[ClientType, MemberType, StorageType]:
|
|
68
|
+
"""Register an async trie index whose member, serializer, and storage types agree.
|
|
69
|
+
|
|
70
|
+
``serializer`` and ``storage`` are instances. The returned index is registered
|
|
71
|
+
and ready to use. Pass the storage client to each index method.
|
|
72
|
+
"""
|
|
73
|
+
return cast(
|
|
74
|
+
AsyncTrieIndex[ClientType, MemberType, StorageType],
|
|
75
|
+
_build(
|
|
76
|
+
key,
|
|
77
|
+
member_type=member_type,
|
|
78
|
+
serializer=serializer,
|
|
79
|
+
storage=storage,
|
|
80
|
+
base=AsyncTrieIndex,
|
|
81
|
+
protocol=AsyncTrieStorage,
|
|
82
|
+
other=TrieStorage,
|
|
83
|
+
),
|
|
84
|
+
)
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def _build(
|
|
88
|
+
key: str,
|
|
89
|
+
*,
|
|
90
|
+
member_type: Any,
|
|
91
|
+
serializer: Any,
|
|
92
|
+
storage: Any,
|
|
93
|
+
base: type[TrieIndex[Any, Any, Any]] | type[AsyncTrieIndex[Any, Any, Any]],
|
|
94
|
+
protocol: type[TrieStorage[Any, Any]] | type[AsyncTrieStorage[Any, Any]],
|
|
95
|
+
other: type[TrieStorage[Any, Any]] | type[AsyncTrieStorage[Any, Any]],
|
|
96
|
+
) -> Any:
|
|
97
|
+
check_key(key)
|
|
98
|
+
instance_class(key, serializer, label="serializer")
|
|
99
|
+
value_type, serializer_storage = serializer_types(key, serializer_class(serializer))
|
|
100
|
+
check_value_type(key, member_type, value_type, label="member type")
|
|
101
|
+
storage_cls = instance_class(key, storage, label="storage")
|
|
102
|
+
storage_type = _storage_type(key, storage_cls, protocol, other)
|
|
103
|
+
check_storage_type(key, serializer_storage, storage_type, storage_cls)
|
|
104
|
+
client_type = storage_client_type(key, storage_cls, protocol)
|
|
105
|
+
return index_class(
|
|
106
|
+
key,
|
|
107
|
+
serializer_instance=serializer,
|
|
108
|
+
storage=storage,
|
|
109
|
+
base=base,
|
|
110
|
+
module=__name__,
|
|
111
|
+
attributes={
|
|
112
|
+
"member": member_type,
|
|
113
|
+
"client_type": client_type,
|
|
114
|
+
"breadcrumbs": NoopBreadcrumbs(),
|
|
115
|
+
},
|
|
116
|
+
)
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def _storage_type(
|
|
120
|
+
key: str,
|
|
121
|
+
storage: type,
|
|
122
|
+
protocol: type,
|
|
123
|
+
other: type,
|
|
124
|
+
) -> Any:
|
|
125
|
+
args = protocol_args(storage, protocol)
|
|
126
|
+
if args is None or len(args) != 2:
|
|
127
|
+
if protocol_args(storage, other) is not None:
|
|
128
|
+
if protocol is TrieStorage:
|
|
129
|
+
raise TypeError(
|
|
130
|
+
f"index {key!r}: {storage.__name__} is asynchronous; "
|
|
131
|
+
"build_trie_index requires TrieStorage"
|
|
132
|
+
)
|
|
133
|
+
raise TypeError(
|
|
134
|
+
f"index {key!r}: {storage.__name__} is synchronous; "
|
|
135
|
+
"build_async_trie_index requires AsyncTrieStorage"
|
|
136
|
+
)
|
|
137
|
+
raise TypeError(
|
|
138
|
+
f"index {key!r}: {storage.__name__} does not declare "
|
|
139
|
+
f"{protocol.__name__}[ClientType, PayloadType]"
|
|
140
|
+
)
|
|
141
|
+
return args[1]
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
"""Synchronous trie index."""
|
|
2
|
+
|
|
3
|
+
from collections.abc import Hashable, Sequence
|
|
4
|
+
from typing import Self
|
|
5
|
+
|
|
6
|
+
from cachebind.indexes._serializer import resolve_serializer
|
|
7
|
+
from cachebind.indexes.tries.base import TrieBase
|
|
8
|
+
from cachebind.storage.tries._values import check_limit
|
|
9
|
+
from cachebind.storage.tries.storage import TrieStorage
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class TrieIndex[ClientType, MemberType, StorageType: Hashable](
|
|
13
|
+
TrieBase[ClientType, MemberType, StorageType]
|
|
14
|
+
):
|
|
15
|
+
"""Sync trie index: member binding, storage key, and the storage that persists it.
|
|
16
|
+
|
|
17
|
+
The suggestion string and the score are stored as given. The member is the payload:
|
|
18
|
+
writes serialize it, and ``search`` deserializes the payloads in rank order.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
storage: TrieStorage[ClientType, StorageType]
|
|
22
|
+
|
|
23
|
+
def add(
|
|
24
|
+
self,
|
|
25
|
+
client: ClientType,
|
|
26
|
+
string: str,
|
|
27
|
+
member: MemberType,
|
|
28
|
+
score: float,
|
|
29
|
+
*,
|
|
30
|
+
increment: bool = False,
|
|
31
|
+
**kwargs,
|
|
32
|
+
) -> str:
|
|
33
|
+
"""Add ``string`` with ``score`` and ``member`` as its payload.
|
|
34
|
+
|
|
35
|
+
A string that is already present gets the new score and payload.
|
|
36
|
+
``increment=True`` adds ``score`` to the stored score instead of replacing it.
|
|
37
|
+
"""
|
|
38
|
+
serializer = resolve_serializer(self.serializer, kwargs)
|
|
39
|
+
self.storage.add(
|
|
40
|
+
client,
|
|
41
|
+
self.key,
|
|
42
|
+
string,
|
|
43
|
+
score,
|
|
44
|
+
serializer.serialize(member),
|
|
45
|
+
increment=increment,
|
|
46
|
+
)
|
|
47
|
+
return self.breadcrumbs.encode(self.key, "")
|
|
48
|
+
|
|
49
|
+
def madd(
|
|
50
|
+
self,
|
|
51
|
+
client: ClientType,
|
|
52
|
+
entries: Sequence[tuple[str, MemberType, float]],
|
|
53
|
+
*,
|
|
54
|
+
increment: bool = False,
|
|
55
|
+
**kwargs,
|
|
56
|
+
) -> list[str]:
|
|
57
|
+
"""Add every suggestion. A repeated string keeps the last score and payload."""
|
|
58
|
+
if not entries:
|
|
59
|
+
return []
|
|
60
|
+
serializer = resolve_serializer(self.serializer, kwargs)
|
|
61
|
+
serialized = serializer.mserialize([member for _string, member, _score in entries])
|
|
62
|
+
stored = [
|
|
63
|
+
(string, score, payload)
|
|
64
|
+
for (string, _member, score), payload in zip(entries, serialized, strict=True)
|
|
65
|
+
]
|
|
66
|
+
self.storage.madd(client, self.key, stored, increment=increment)
|
|
67
|
+
crumb = self.breadcrumbs.encode(self.key, "")
|
|
68
|
+
return [crumb] * len(entries)
|
|
69
|
+
|
|
70
|
+
def remove(self, client: ClientType, string: str) -> None:
|
|
71
|
+
"""Remove the suggestion ``string``. A missing string is not an error."""
|
|
72
|
+
self.storage.remove(client, self.key, string)
|
|
73
|
+
|
|
74
|
+
def evict(self, client: ClientType, identifier: str) -> None:
|
|
75
|
+
"""Not supported: trie tags do not identify one entry."""
|
|
76
|
+
raise NotImplementedError("evict is not supported for trie indexes")
|
|
77
|
+
|
|
78
|
+
def mremove(self, client: ClientType, strings: Sequence[str]) -> None:
|
|
79
|
+
"""Remove every suggestion string. Missing strings are not an error."""
|
|
80
|
+
if not strings:
|
|
81
|
+
return
|
|
82
|
+
self.storage.mremove(client, self.key, strings)
|
|
83
|
+
|
|
84
|
+
def search(
|
|
85
|
+
self,
|
|
86
|
+
client: ClientType,
|
|
87
|
+
prefix: str,
|
|
88
|
+
*,
|
|
89
|
+
fuzzy: bool = False,
|
|
90
|
+
limit: int = 10,
|
|
91
|
+
**kwargs,
|
|
92
|
+
) -> list[MemberType]:
|
|
93
|
+
"""Return members whose suggestion string matches ``prefix``, in rank order.
|
|
94
|
+
|
|
95
|
+
``limit`` is the maximum number of members. ``fuzzy`` allows a one-edit prefix.
|
|
96
|
+
Members are deserialized from the stored payloads.
|
|
97
|
+
"""
|
|
98
|
+
check_limit(limit)
|
|
99
|
+
serializer = resolve_serializer(self.serializer, kwargs)
|
|
100
|
+
raw = self.storage.search(client, self.key, prefix, fuzzy=fuzzy, limit=limit)
|
|
101
|
+
return serializer.mdeserialize(raw)
|
|
102
|
+
|
|
103
|
+
def length(self, client: ClientType) -> int:
|
|
104
|
+
"""Return the number of suggestion strings in the trie."""
|
|
105
|
+
return self.storage.length(client, self.key)
|
|
106
|
+
|
|
107
|
+
def swap(self, client: ClientType) -> Self:
|
|
108
|
+
"""Rename this index aside and return an unregistered index for that data."""
|
|
109
|
+
return self.detach(self.storage.swap(client, self.key))
|
|
110
|
+
|
|
111
|
+
def drop(self, client: ClientType) -> None:
|
|
112
|
+
"""Delete the key this index is bound to. A missing key is not an error."""
|
|
113
|
+
self.storage.drop(client, self.key)
|