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
@@ -0,0 +1,170 @@
1
+ """Build a registered key-value 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.key_value.async_index import AsyncKeyValueIndex
18
+ from cachebind.indexes.key_value.index import KeyValueIndex
19
+ from cachebind.serializers.serializer import Serializer
20
+ from cachebind.tagging import Breadcrumbs, ColonBreadcrumbs, NoopBreadcrumbs
21
+ from cachebind.storage.key_value.async_storage import AsyncKeyValueStorage
22
+ from cachebind.storage.key_value.storage import KeyValueStorage
23
+
24
+
25
+ def build_key_value_index[
26
+ ClientType,
27
+ IdType: Hashable,
28
+ ModelType,
29
+ StorageType,
30
+ Storage: KeyValueStorage[ClientType, str, StorageType],
31
+ ](
32
+ key: str,
33
+ *,
34
+ id_type: type[IdType],
35
+ model_type: type[ModelType],
36
+ serializer: Serializer[ModelType, StorageType],
37
+ storage: Storage,
38
+ breadcrumbs: Breadcrumbs | None = None,
39
+ ) -> KeyValueIndex[ClientType, IdType, ModelType, StorageType]:
40
+ """Register a sync key-value index whose id, model, serializer, and storage types agree.
41
+
42
+ ``serializer`` and ``storage`` are instances. The returned index is registered
43
+ and ready to use. Pass the storage client to each index method.
44
+ """
45
+ return cast(
46
+ KeyValueIndex[ClientType, IdType, ModelType, StorageType],
47
+ _build(
48
+ key,
49
+ id_type=id_type,
50
+ model_type=model_type,
51
+ serializer=serializer,
52
+ storage=storage,
53
+ breadcrumbs=breadcrumbs,
54
+ base=KeyValueIndex,
55
+ protocol=KeyValueStorage,
56
+ other=AsyncKeyValueStorage,
57
+ ),
58
+ )
59
+
60
+
61
+ def build_async_key_value_index[
62
+ ClientType,
63
+ IdType: Hashable,
64
+ ModelType,
65
+ StorageType,
66
+ Storage: AsyncKeyValueStorage[ClientType, str, StorageType],
67
+ ](
68
+ key: str,
69
+ *,
70
+ id_type: type[IdType],
71
+ model_type: type[ModelType],
72
+ serializer: Serializer[ModelType, StorageType],
73
+ storage: Storage,
74
+ breadcrumbs: Breadcrumbs | None = None,
75
+ ) -> AsyncKeyValueIndex[ClientType, IdType, ModelType, StorageType]:
76
+ """Register an async key-value index whose id, model, serializer, and storage types agree.
77
+
78
+ ``serializer`` and ``storage`` are instances. The returned index is registered
79
+ and ready to use. Pass the storage client to each index method.
80
+ """
81
+ return cast(
82
+ AsyncKeyValueIndex[ClientType, IdType, ModelType, StorageType],
83
+ _build(
84
+ key,
85
+ id_type=id_type,
86
+ model_type=model_type,
87
+ serializer=serializer,
88
+ storage=storage,
89
+ breadcrumbs=breadcrumbs,
90
+ base=AsyncKeyValueIndex,
91
+ protocol=AsyncKeyValueStorage,
92
+ other=KeyValueStorage,
93
+ ),
94
+ )
95
+
96
+
97
+ def _build(
98
+ key: str,
99
+ *,
100
+ id_type: Any,
101
+ model_type: Any,
102
+ serializer: Any,
103
+ storage: Any,
104
+ breadcrumbs: Breadcrumbs | None,
105
+ base: type[KeyValueIndex[Any, Any, Any, Any]] | type[AsyncKeyValueIndex[Any, Any, Any, Any]],
106
+ protocol: type[KeyValueStorage[Any, Any, Any]] | type[AsyncKeyValueStorage[Any, Any, Any]],
107
+ other: type[KeyValueStorage[Any, Any, Any]] | type[AsyncKeyValueStorage[Any, Any, Any]],
108
+ ) -> Any:
109
+ check_key(key)
110
+ _check_id_type(key, id_type)
111
+ instance_class(key, serializer, label="serializer")
112
+ value_type, serializer_storage = serializer_types(key, serializer_class(serializer))
113
+ check_value_type(key, model_type, value_type, label="model type")
114
+ storage_cls = instance_class(key, storage, label="storage")
115
+ storage_type = _storage_type(key, storage_cls, protocol, other)
116
+ check_storage_type(key, serializer_storage, storage_type, storage_cls)
117
+ client_type = storage_client_type(key, storage_cls, protocol)
118
+ if breadcrumbs is None:
119
+ breadcrumbs = ColonBreadcrumbs()
120
+ else:
121
+ instance_class(key, breadcrumbs, label="breadcrumbs")
122
+ return index_class(
123
+ key,
124
+ serializer_instance=serializer,
125
+ storage=storage,
126
+ base=base,
127
+ module=__name__,
128
+ attributes={
129
+ "identifier": id_type,
130
+ "model": model_type,
131
+ "client_type": client_type,
132
+ "breadcrumbs": breadcrumbs,
133
+ },
134
+ )
135
+
136
+
137
+ def _check_id_type(key: str, id_type: Any) -> None:
138
+ if isinstance(id_type, type) and id_type.__hash__ is not None:
139
+ return
140
+ raise TypeError(f"index {key!r}: id type must be a hashable class, got {id_type!r}")
141
+
142
+
143
+ def _storage_type(
144
+ key: str,
145
+ storage: type,
146
+ protocol: type,
147
+ other: type,
148
+ ) -> Any:
149
+ args = protocol_args(storage, protocol)
150
+ if args is None or len(args) != 3:
151
+ if protocol_args(storage, other) is not None:
152
+ if protocol is KeyValueStorage:
153
+ raise TypeError(
154
+ f"index {key!r}: {storage.__name__} is asynchronous; "
155
+ "build_key_value_index requires KeyValueStorage"
156
+ )
157
+ raise TypeError(
158
+ f"index {key!r}: {storage.__name__} is synchronous; "
159
+ "build_async_key_value_index requires AsyncKeyValueStorage"
160
+ )
161
+ raise TypeError(
162
+ f"index {key!r}: {storage.__name__} does not declare "
163
+ f"{protocol.__name__}[ClientType, FieldType, StorageType]"
164
+ )
165
+ field_type, storage_type = args[1:]
166
+ if field_type is not str:
167
+ raise TypeError(
168
+ f"index {key!r}: {storage.__name__} field type must be str, got {field_type!r}"
169
+ )
170
+ return storage_type
@@ -0,0 +1,142 @@
1
+ """Synchronous key-value index."""
2
+
3
+ from collections.abc import Hashable, Iterable, 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.storage import KeyValueStorage
10
+
11
+ BATCH = 100
12
+
13
+
14
+ class KeyValueIndex[ClientType, IdType: Hashable, ModelType, StorageType](
15
+ KeyValueBase[ClientType, IdType, ModelType, StorageType]
16
+ ):
17
+ """Sync 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: KeyValueStorage[ClientType, str, StorageType]
23
+
24
+ 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 = self.storage.get(client, self.key, str(id))
33
+ if raw is None:
34
+ return None
35
+ return serializer.deserialize(raw)
36
+
37
+ 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
+ self.storage.set(client, self.key, field, serializer.serialize(value), ttl=ttl)
50
+ return self.breadcrumbs.encode(self.key, field)
51
+
52
+ def delete(self, client: ClientType, id: IdType) -> None:
53
+ """Remove ``id``. A missing id is not an error."""
54
+ self.storage.delete(client, self.key, str(id))
55
+
56
+ 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
+ self.storage.delete(client, self.key, identifier)
62
+
63
+ 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
+ self.storage.mdelete(client, self.key, [str(id) for id in ids])
68
+
69
+ def exists(self, client: ClientType, id: IdType) -> bool:
70
+ """Return whether ``id`` is present."""
71
+ return self.storage.exists(client, self.key, str(id))
72
+
73
+ 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 = 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
+ 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
+ self.storage.mset(client, self.key, mapping, ttl=ttl)
104
+ return [self.breadcrumbs.encode(self.key, field) for field in fields]
105
+
106
+ def swap(self, client: ClientType) -> Self:
107
+ """Rename this index aside and return an unregistered index for that data."""
108
+ return self.detach(self.storage.swap(client, self.key))
109
+
110
+ def drop(self, client: ClientType) -> None:
111
+ """Delete the key this index is bound to. A missing key is not an error."""
112
+ self.storage.drop(client, self.key)
113
+
114
+ def iter(
115
+ self,
116
+ client: ClientType,
117
+ **kwargs,
118
+ ) -> Iterator[tuple[str, ModelType]]:
119
+ """Yield each stored id and model under this index key."""
120
+ serializer = resolve_serializer(self.serializer, kwargs)
121
+ return pairs(self.storage.iter(client, self.key), serializer)
122
+
123
+
124
+ def pairs[StorageType, ValueType](
125
+ raw: Iterable[tuple[str, StorageType]], serializer: Serializer[ValueType, StorageType]
126
+ ) -> Iterator[tuple[str, ValueType]]:
127
+ """Yield stored ids and deserialized values, one ``mdeserialize`` per batch."""
128
+ batch: list[tuple[str, StorageType]] = []
129
+ for item in raw:
130
+ batch.append(item)
131
+ if len(batch) == BATCH:
132
+ yield from _pairs(batch, serializer)
133
+ batch = []
134
+ if batch:
135
+ yield from _pairs(batch, serializer)
136
+
137
+
138
+ def _pairs[StorageType, ValueType](
139
+ batch: list[tuple[str, StorageType]], serializer: Serializer[ValueType, StorageType]
140
+ ) -> Iterator[tuple[str, ValueType]]:
141
+ decoded = serializer.mdeserialize([value for _field, value in batch])
142
+ return zip((field for field, _value in batch), decoded, strict=True)
@@ -0,0 +1,17 @@
1
+ """Ordered-set indexes bind a member to ordered-set storage and register that binding by key."""
2
+
3
+ from cachebind.indexes.ordered_sets.async_index import AsyncOrderedSetIndex
4
+ from cachebind.indexes.ordered_sets.base import OrderedSetBase
5
+ from cachebind.indexes.ordered_sets.builder import (
6
+ build_async_ordered_set_index,
7
+ build_ordered_set_index,
8
+ )
9
+ from cachebind.indexes.ordered_sets.index import OrderedSetIndex
10
+
11
+ __all__ = [
12
+ "AsyncOrderedSetIndex",
13
+ "OrderedSetBase",
14
+ "OrderedSetIndex",
15
+ "build_async_ordered_set_index",
16
+ "build_ordered_set_index",
17
+ ]
@@ -0,0 +1,221 @@
1
+ """Asynchronous ordered-set index."""
2
+
3
+ from collections.abc import AsyncIterable, AsyncIterator, Hashable, 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.ordered_sets.base import OrderedSetBase, _empty_range
9
+ from cachebind.serializers.serializer import Serializer
10
+ from cachebind.storage.ordered_sets.async_storage import AsyncOrderedSetStorage
11
+
12
+ BATCH = 100
13
+
14
+
15
+ class AsyncOrderedSetIndex[ClientType, MemberType, StorageType: Hashable](
16
+ OrderedSetBase[ClientType, MemberType, StorageType]
17
+ ):
18
+ """Async ordered-set index: member binding, storage key, and the storage that persists it.
19
+
20
+ Writes serialize the member and pass the score through. Reads deserialize members.
21
+ """
22
+
23
+ storage: AsyncOrderedSetStorage[ClientType, StorageType]
24
+
25
+ async def add(
26
+ self,
27
+ client: ClientType,
28
+ member: MemberType,
29
+ score: float,
30
+ **kwargs,
31
+ ) -> str:
32
+ """Add ``member`` with ``score``. A member that is already present gets the new score."""
33
+ serializer = resolve_serializer(self.serializer, kwargs)
34
+ stored = serializer.serialize(member)
35
+ await self.storage.add(client, self.key, stored, score)
36
+ return self.breadcrumbs.encode(self.key, storage_identifier(stored))
37
+
38
+ async def madd(
39
+ self,
40
+ client: ClientType,
41
+ members: Sequence[tuple[MemberType, float]],
42
+ **kwargs,
43
+ ) -> list[str]:
44
+ """Add every member with its score. A repeated member keeps the last score."""
45
+ if not members:
46
+ return []
47
+ serializer = resolve_serializer(self.serializer, kwargs)
48
+ serialized = serializer.mserialize([member for member, _score in members])
49
+ scores = (score for _member, score in members)
50
+ await self.storage.madd(client, self.key, list(zip(serialized, scores, strict=True)))
51
+ return [
52
+ self.breadcrumbs.encode(self.key, storage_identifier(value)) for value in serialized
53
+ ]
54
+
55
+ async def remove(
56
+ self,
57
+ client: ClientType,
58
+ member: MemberType,
59
+ **kwargs,
60
+ ) -> None:
61
+ """Remove ``member``. A missing member is not an error."""
62
+ serializer = resolve_serializer(self.serializer, kwargs)
63
+ await self.storage.remove(client, self.key, serializer.serialize(member))
64
+
65
+ async def evict(self, client: ClientType, identifier: str) -> None:
66
+ """Remove the entry for ``identifier``. A missing entry is not an error.
67
+
68
+ ``identifier`` is the tag payload for one member (not the full encoded tag).
69
+ """
70
+ await self.storage.remove(client, self.key, cast(StorageType, identifier))
71
+
72
+ async def mremove(
73
+ self,
74
+ client: ClientType,
75
+ members: Sequence[MemberType],
76
+ **kwargs,
77
+ ) -> None:
78
+ """Remove every member. Missing members are not an error."""
79
+ if not members:
80
+ return
81
+ serializer = resolve_serializer(self.serializer, kwargs)
82
+ await self.storage.mremove(client, self.key, serializer.mserialize(members))
83
+
84
+ async def contains(
85
+ self,
86
+ client: ClientType,
87
+ member: MemberType,
88
+ **kwargs,
89
+ ) -> bool:
90
+ """Return whether ``member`` is in the ordered set."""
91
+ serializer = resolve_serializer(self.serializer, kwargs)
92
+ return await self.storage.contains(client, self.key, serializer.serialize(member))
93
+
94
+ async def score(
95
+ self,
96
+ client: ClientType,
97
+ member: MemberType,
98
+ **kwargs,
99
+ ) -> float | None:
100
+ """Return the score of ``member``, or ``None`` when it is missing."""
101
+ serializer = resolve_serializer(self.serializer, kwargs)
102
+ return await self.storage.score(client, self.key, serializer.serialize(member))
103
+
104
+ async def rank(
105
+ self,
106
+ client: ClientType,
107
+ member: MemberType,
108
+ **kwargs,
109
+ ) -> int | None:
110
+ """Return the 0-based ascending rank of ``member``, or ``None`` when it is missing."""
111
+ serializer = resolve_serializer(self.serializer, kwargs)
112
+ return await self.storage.rank(client, self.key, serializer.serialize(member))
113
+
114
+ async def range(
115
+ self,
116
+ client: ClientType,
117
+ start: int,
118
+ stop: int,
119
+ **kwargs,
120
+ ) -> list[MemberType]:
121
+ """Return members from ``start`` through ``stop``, both inclusive."""
122
+ if _empty_range(start, stop):
123
+ return []
124
+ serializer = resolve_serializer(self.serializer, kwargs)
125
+ raw = await self.storage.range(client, self.key, start, stop)
126
+ return serializer.mdeserialize(raw)
127
+
128
+ async def range_with_scores(
129
+ self,
130
+ client: ClientType,
131
+ start: int,
132
+ stop: int,
133
+ **kwargs,
134
+ ) -> list[tuple[MemberType, float]]:
135
+ """Return members and scores from ``start`` through ``stop``, both inclusive."""
136
+ if _empty_range(start, stop):
137
+ return []
138
+ serializer = resolve_serializer(self.serializer, kwargs)
139
+ raw = await self.storage.range_with_scores(client, self.key, start, stop)
140
+ members = serializer.mdeserialize([member for member, _score in raw])
141
+ return list(zip(members, (score for _member, score in raw), strict=True))
142
+
143
+ async def rev_rank(
144
+ self,
145
+ client: ClientType,
146
+ member: MemberType,
147
+ **kwargs,
148
+ ) -> int | None:
149
+ """Return the 0-based descending rank of ``member``, or ``None`` when it is missing."""
150
+ serializer = resolve_serializer(self.serializer, kwargs)
151
+ return await self.storage.rev_rank(client, self.key, serializer.serialize(member))
152
+
153
+ async def rev_range(
154
+ self,
155
+ client: ClientType,
156
+ start: int,
157
+ stop: int,
158
+ **kwargs,
159
+ ) -> list[MemberType]:
160
+ """Return members from ``start`` through ``stop``, both inclusive, highest score first."""
161
+ if _empty_range(start, stop):
162
+ return []
163
+ serializer = resolve_serializer(self.serializer, kwargs)
164
+ raw = await self.storage.rev_range(client, self.key, start, stop)
165
+ return serializer.mdeserialize(raw)
166
+
167
+ async def rev_range_with_scores(
168
+ self,
169
+ client: ClientType,
170
+ start: int,
171
+ stop: int,
172
+ **kwargs,
173
+ ) -> list[tuple[MemberType, float]]:
174
+ """Return members and scores from ``start`` through ``stop``, highest score first."""
175
+ if _empty_range(start, stop):
176
+ return []
177
+ serializer = resolve_serializer(self.serializer, kwargs)
178
+ raw = await self.storage.rev_range_with_scores(client, self.key, start, stop)
179
+ members = serializer.mdeserialize([member for member, _score in raw])
180
+ return list(zip(members, (score for _member, score in raw), strict=True))
181
+
182
+ async def swap(self, client: ClientType) -> Self:
183
+ """Rename this index aside and return an unregistered index for that data."""
184
+ return self.detach(await self.storage.swap(client, self.key))
185
+
186
+ async def drop(self, client: ClientType) -> None:
187
+ """Delete the key this index is bound to. A missing key is not an error."""
188
+ await self.storage.drop(client, self.key)
189
+
190
+ async def iter(
191
+ self,
192
+ client: ClientType,
193
+ **kwargs,
194
+ ) -> AsyncIterator[tuple[MemberType, float]]:
195
+ """Yield each member and score under this index key, lowest score first."""
196
+ serializer = resolve_serializer(self.serializer, kwargs)
197
+ async for pair in async_scored(self.storage.iter(client, self.key), serializer):
198
+ yield pair
199
+
200
+
201
+ async def async_scored[StorageType, ValueType](
202
+ raw: AsyncIterable[tuple[StorageType, float]], serializer: Serializer[ValueType, StorageType]
203
+ ) -> AsyncIterator[tuple[ValueType, float]]:
204
+ """Yield deserialized members and their scores, one ``mdeserialize`` per batch."""
205
+ batch: list[tuple[StorageType, float]] = []
206
+ async for item in raw:
207
+ batch.append(item)
208
+ if len(batch) == BATCH:
209
+ for decoded in _scored(batch, serializer):
210
+ yield decoded
211
+ batch = []
212
+ if batch:
213
+ for decoded in _scored(batch, serializer):
214
+ yield decoded
215
+
216
+
217
+ def _scored[StorageType, ValueType](
218
+ batch: list[tuple[StorageType, float]], serializer: Serializer[ValueType, StorageType]
219
+ ) -> Iterator[tuple[ValueType, float]]:
220
+ decoded = serializer.mdeserialize([member for member, _score in batch])
221
+ return zip(decoded, (score for _member, score in batch), strict=True)
@@ -0,0 +1,38 @@
1
+ """Shared ordered-set 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.ordered_sets.async_storage import AsyncOrderedSetStorage
11
+ from cachebind.storage.ordered_sets.storage import OrderedSetStorage
12
+
13
+
14
+ class OrderedSetBase[ClientType, MemberType, StorageType: Hashable](Index):
15
+ """Member, serializer, storage key, and storage for an ordered-set index.
16
+
17
+ ``key`` is the ordered set name. ``storage`` stores serialized members and scores.
18
+ Each call receives the storage client.
19
+ """
20
+
21
+ member: type[MemberType]
22
+ breadcrumbs: Breadcrumbs = NoopBreadcrumbs()
23
+ serializer: Serializer[MemberType, StorageType]
24
+ storage: (
25
+ OrderedSetStorage[ClientType, StorageType]
26
+ | AsyncOrderedSetStorage[ClientType, StorageType]
27
+ )
28
+
29
+
30
+ def _empty_range(start: int, stop: int) -> bool:
31
+ """Return whether this inclusive rank window has no members.
32
+
33
+ Both ends must be negative, or both non-negative, and ``start`` must be past
34
+ ``stop``. Mixed signs depend on the length of the ordered set.
35
+ """
36
+ if (start >= 0) != (stop >= 0):
37
+ return False
38
+ return start > stop