cachebind 1.0.0__tar.gz
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-1.0.0/.gitignore +12 -0
- cachebind-1.0.0/LICENSE +21 -0
- cachebind-1.0.0/PKG-INFO +171 -0
- cachebind-1.0.0/README.md +153 -0
- cachebind-1.0.0/docs/leaderboard.md +180 -0
- cachebind-1.0.0/docs/tag-based-caching.md +191 -0
- cachebind-1.0.0/docs/trie.md +230 -0
- cachebind-1.0.0/docs/write-back-caching.md +60 -0
- cachebind-1.0.0/pyproject.toml +21 -0
- cachebind-1.0.0/src/cachebind/__init__.py +121 -0
- cachebind-1.0.0/src/cachebind/indexes/__init__.py +61 -0
- cachebind-1.0.0/src/cachebind/indexes/_breadcrumb.py +10 -0
- cachebind-1.0.0/src/cachebind/indexes/_builder.py +171 -0
- cachebind-1.0.0/src/cachebind/indexes/_serializer.py +17 -0
- cachebind-1.0.0/src/cachebind/indexes/base.py +51 -0
- cachebind-1.0.0/src/cachebind/indexes/evict.py +21 -0
- cachebind-1.0.0/src/cachebind/indexes/key_value/__init__.py +14 -0
- cachebind-1.0.0/src/cachebind/indexes/key_value/async_index.py +145 -0
- cachebind-1.0.0/src/cachebind/indexes/key_value/base.py +30 -0
- cachebind-1.0.0/src/cachebind/indexes/key_value/builder.py +170 -0
- cachebind-1.0.0/src/cachebind/indexes/key_value/index.py +142 -0
- cachebind-1.0.0/src/cachebind/indexes/ordered_sets/__init__.py +17 -0
- cachebind-1.0.0/src/cachebind/indexes/ordered_sets/async_index.py +221 -0
- cachebind-1.0.0/src/cachebind/indexes/ordered_sets/base.py +38 -0
- cachebind-1.0.0/src/cachebind/indexes/ordered_sets/builder.py +146 -0
- cachebind-1.0.0/src/cachebind/indexes/ordered_sets/index.py +218 -0
- cachebind-1.0.0/src/cachebind/indexes/registry.py +38 -0
- cachebind-1.0.0/src/cachebind/indexes/sets/__init__.py +14 -0
- cachebind-1.0.0/src/cachebind/indexes/sets/async_index.py +124 -0
- cachebind-1.0.0/src/cachebind/indexes/sets/base.py +24 -0
- cachebind-1.0.0/src/cachebind/indexes/sets/builder.py +146 -0
- cachebind-1.0.0/src/cachebind/indexes/sets/index.py +121 -0
- cachebind-1.0.0/src/cachebind/indexes/tries/__init__.py +14 -0
- cachebind-1.0.0/src/cachebind/indexes/tries/async_index.py +113 -0
- cachebind-1.0.0/src/cachebind/indexes/tries/base.py +25 -0
- cachebind-1.0.0/src/cachebind/indexes/tries/builder.py +141 -0
- cachebind-1.0.0/src/cachebind/indexes/tries/index.py +113 -0
- cachebind-1.0.0/src/cachebind/serializers/__init__.py +29 -0
- cachebind-1.0.0/src/cachebind/serializers/bool_serializer.py +21 -0
- cachebind-1.0.0/src/cachebind/serializers/dataclass_serializer.py +102 -0
- cachebind-1.0.0/src/cachebind/serializers/datetime_serializer.py +22 -0
- cachebind-1.0.0/src/cachebind/serializers/dict_serializer.py +29 -0
- cachebind-1.0.0/src/cachebind/serializers/float_serializer.py +18 -0
- cachebind-1.0.0/src/cachebind/serializers/int_serializer.py +20 -0
- cachebind-1.0.0/src/cachebind/serializers/noop_serializer.py +19 -0
- cachebind-1.0.0/src/cachebind/serializers/pydantic_serializer.py +29 -0
- cachebind-1.0.0/src/cachebind/serializers/serializer.py +24 -0
- cachebind-1.0.0/src/cachebind/serializers/str_serializer.py +13 -0
- cachebind-1.0.0/src/cachebind/serializers/uuid_serializer.py +22 -0
- cachebind-1.0.0/src/cachebind/storage/__init__.py +67 -0
- cachebind-1.0.0/src/cachebind/storage/_redis.py +80 -0
- cachebind-1.0.0/src/cachebind/storage/key_value/__init__.py +37 -0
- cachebind-1.0.0/src/cachebind/storage/key_value/async_redis_hash_storage.py +73 -0
- cachebind-1.0.0/src/cachebind/storage/key_value/async_redis_string_storage.py +72 -0
- cachebind-1.0.0/src/cachebind/storage/key_value/async_storage.py +76 -0
- cachebind-1.0.0/src/cachebind/storage/key_value/redis_hash_storage.py +73 -0
- cachebind-1.0.0/src/cachebind/storage/key_value/redis_string_storage.py +72 -0
- cachebind-1.0.0/src/cachebind/storage/key_value/storage.py +74 -0
- cachebind-1.0.0/src/cachebind/storage/ordered_sets/__init__.py +29 -0
- cachebind-1.0.0/src/cachebind/storage/ordered_sets/_values.py +60 -0
- cachebind-1.0.0/src/cachebind/storage/ordered_sets/async_redis_ordered_set_storage.py +91 -0
- cachebind-1.0.0/src/cachebind/storage/ordered_sets/async_storage.py +89 -0
- cachebind-1.0.0/src/cachebind/storage/ordered_sets/redis_ordered_set_storage.py +88 -0
- cachebind-1.0.0/src/cachebind/storage/ordered_sets/storage.py +85 -0
- cachebind-1.0.0/src/cachebind/storage/sets/__init__.py +27 -0
- cachebind-1.0.0/src/cachebind/storage/sets/async_redis_set_storage.py +54 -0
- cachebind-1.0.0/src/cachebind/storage/sets/async_storage.py +49 -0
- cachebind-1.0.0/src/cachebind/storage/sets/redis_set_storage.py +52 -0
- cachebind-1.0.0/src/cachebind/storage/sets/storage.py +49 -0
- cachebind-1.0.0/src/cachebind/storage/tries/__init__.py +27 -0
- cachebind-1.0.0/src/cachebind/storage/tries/_reply.py +20 -0
- cachebind-1.0.0/src/cachebind/storage/tries/_values.py +36 -0
- cachebind-1.0.0/src/cachebind/storage/tries/async_redis_trie_storage.py +81 -0
- cachebind-1.0.0/src/cachebind/storage/tries/async_storage.py +78 -0
- cachebind-1.0.0/src/cachebind/storage/tries/redis_trie_storage.py +79 -0
- cachebind-1.0.0/src/cachebind/storage/tries/storage.py +78 -0
- cachebind-1.0.0/src/cachebind/tagging/__init__.py +19 -0
- cachebind-1.0.0/src/cachebind/tagging/breadcrumbs/__init__.py +11 -0
- cachebind-1.0.0/src/cachebind/tagging/breadcrumbs/colon_breadcrumbs.py +20 -0
- cachebind-1.0.0/src/cachebind/tagging/breadcrumbs/noop_breadcrumbs.py +15 -0
- cachebind-1.0.0/src/cachebind/tagging/breadcrumbs/protocol.py +15 -0
- cachebind-1.0.0/src/cachebind/tagging/tag_keeper/__init__.py +12 -0
- cachebind-1.0.0/src/cachebind/tagging/tag_keeper/_keys.py +10 -0
- cachebind-1.0.0/src/cachebind/tagging/tag_keeper/async_set_tag_keeper.py +47 -0
- cachebind-1.0.0/src/cachebind/tagging/tag_keeper/protocol.py +37 -0
- cachebind-1.0.0/src/cachebind/tagging/tag_keeper/set_tag_keeper.py +47 -0
- cachebind-1.0.0/tests/test_breadcrumbs.py +34 -0
- cachebind-1.0.0/tests/test_index_builder.py +613 -0
- cachebind-1.0.0/tests/test_index_tags.py +619 -0
- cachebind-1.0.0/tests/test_interfaces.py +513 -0
- cachebind-1.0.0/tests/test_ordered_set_index_builder.py +521 -0
- cachebind-1.0.0/tests/test_package.py +17 -0
- cachebind-1.0.0/tests/test_pydantic_serializer.py +42 -0
- cachebind-1.0.0/tests/test_redis_hash_storage.py +187 -0
- cachebind-1.0.0/tests/test_redis_ordered_set_storage.py +201 -0
- cachebind-1.0.0/tests/test_redis_set_storage.py +123 -0
- cachebind-1.0.0/tests/test_redis_string_storage.py +184 -0
- cachebind-1.0.0/tests/test_redis_trie_storage.py +232 -0
- cachebind-1.0.0/tests/test_serializers.py +236 -0
- cachebind-1.0.0/tests/test_set_index_builder.py +376 -0
- cachebind-1.0.0/tests/test_tag_keeper.py +246 -0
- cachebind-1.0.0/tests/test_trie_index_builder.py +566 -0
- cachebind-1.0.0/uv.lock +277 -0
cachebind-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 goroba
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
cachebind-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: cachebind
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: A Python library.
|
|
5
|
+
Author: goroba
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Requires-Python: >=3.12
|
|
9
|
+
Provides-Extra: dev
|
|
10
|
+
Requires-Dist: fakeredis>=2; extra == 'dev'
|
|
11
|
+
Requires-Dist: pydantic>=2; extra == 'dev'
|
|
12
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
13
|
+
Provides-Extra: pydantic
|
|
14
|
+
Requires-Dist: pydantic>=2; extra == 'pydantic'
|
|
15
|
+
Provides-Extra: redis
|
|
16
|
+
Requires-Dist: redis>=5; extra == 'redis'
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
|
|
19
|
+
# cachebind
|
|
20
|
+
|
|
21
|
+
A Python library that names a cache binding — one storage key, a serializer, and a storage — and reads or writes Python values through it.
|
|
22
|
+
|
|
23
|
+
**What is it for?** Cachebind is a way to name a cache binding and use it from application code. An index holds one storage key, a serializer, and a storage. You build it once. Each call takes your storage client and reads or writes a Python value through that binding. Redis storages are included. Any storage that matches the protocol works the same way.
|
|
24
|
+
|
|
25
|
+
**What can an index store?** A key-value index stores one model per id. A set index stores members in one set. An ordered set index stores members with scores, lowest score first. A trie index stores suggestion strings with scores and keeps each member as the payload. `search` returns those members in rank order. Each has a sync builder and an async builder.
|
|
26
|
+
|
|
27
|
+
## Indexes
|
|
28
|
+
|
|
29
|
+
Build an index once with `build_async_key_value_index`, `build_async_set_index`, `build_async_ordered_set_index`, or `build_async_trie_index`. Pass a key, the value type, a serializer instance, and a storage instance. Optionally pass `breadcrumbs` (default `ColonBreadcrumbs`) on key-value, set, and ordered-set builders. Trie indexes always use `NoopBreadcrumbs` and do not accept `breadcrumbs`. Then pass a storage client into every call.
|
|
30
|
+
|
|
31
|
+
`set` and `add` return one breadcrumb. `mset` and `madd` return one breadcrumb per item. By default, breadcrumbs encode the index key and eviction identifier. With `NoopBreadcrumbs`, writes return an empty breadcrumb. Decode a breadcrumb to get the index name and identifier, then call `evict(client, identifier)` on that index (not supported on trie indexes).
|
|
32
|
+
|
|
33
|
+
A **tag keeper** groups those breadcrumbs in Redis sets. Create `SetTagKeeper(storage=RedisSetStorage())` or `AsyncSetTagKeeper` with async set storage; optional `name` defaults to `"default"`, optional `breadcrumbs` defaults to `ColonBreadcrumbs()` for decoding on `evict`. Each logical `tag` is one set at `tag_keeper:{name}:{tag}`. After writes, call `add(client, tag, breadcrumb)` or `madd(client, tag, breadcrumbs)`; call `evict(client, tag)` to decode every breadcrumb in that set, evict through the index registry, and delete the set.
|
|
34
|
+
|
|
35
|
+
```python
|
|
36
|
+
from uuid import UUID
|
|
37
|
+
|
|
38
|
+
from pydantic import BaseModel
|
|
39
|
+
from redis.asyncio import Redis as AsyncRedis
|
|
40
|
+
|
|
41
|
+
from cachebind import build_async_key_value_index
|
|
42
|
+
from cachebind.serializers.pydantic_serializer import PydanticSerializer
|
|
43
|
+
from cachebind.storage import AsyncRedisHashStorage
|
|
44
|
+
|
|
45
|
+
class User(BaseModel):
|
|
46
|
+
id: UUID
|
|
47
|
+
name: str
|
|
48
|
+
|
|
49
|
+
ada = User(id=UUID("12345678-1234-5678-1234-567812345678"), name="Ada")
|
|
50
|
+
|
|
51
|
+
users = build_async_key_value_index(
|
|
52
|
+
"users",
|
|
53
|
+
id_type=UUID,
|
|
54
|
+
model_type=User,
|
|
55
|
+
serializer=PydanticSerializer(User),
|
|
56
|
+
storage=AsyncRedisHashStorage(),
|
|
57
|
+
)
|
|
58
|
+
|
|
59
|
+
async def main() -> None:
|
|
60
|
+
client = AsyncRedis(decode_responses=True)
|
|
61
|
+
await users.set(client, ada.id, ada, ttl=60)
|
|
62
|
+
value = await users.get(client, ada.id)
|
|
63
|
+
await users.delete(client, ada.id)
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`ttl` is a whole number of seconds on `set` and `mset`. Omit it, or pass `None`, and the write does not expire. `mset` applies that one TTL to every id. `delete` removes one id. `mdelete` removes every given id. A missing id is not an error.
|
|
67
|
+
|
|
68
|
+
Inside `main`, the same client works for a set index.
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
from cachebind import IntSerializer, build_async_set_index
|
|
72
|
+
from cachebind.storage import AsyncRedisSetStorage
|
|
73
|
+
|
|
74
|
+
active = build_async_set_index(
|
|
75
|
+
"active_users",
|
|
76
|
+
member_type=int,
|
|
77
|
+
serializer=IntSerializer(),
|
|
78
|
+
storage=AsyncRedisSetStorage(),
|
|
79
|
+
)
|
|
80
|
+
|
|
81
|
+
await active.add(client, 1)
|
|
82
|
+
present = await active.contains(client, 1)
|
|
83
|
+
await active.remove(client, 1)
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
`remove` drops one member. A missing member is not an error. Sets have no TTL.
|
|
87
|
+
|
|
88
|
+
An ordered set uses the same client. Each member has one score. Adding a member that is already present updates its score. `rank` is 0-based, from the lowest score. `range` includes both ends. Ordered sets have no TTL.
|
|
89
|
+
|
|
90
|
+
```python
|
|
91
|
+
from cachebind import IntSerializer, build_async_ordered_set_index
|
|
92
|
+
from cachebind.storage import AsyncRedisOrderedSetStorage
|
|
93
|
+
|
|
94
|
+
ranking = build_async_ordered_set_index(
|
|
95
|
+
"user_scores",
|
|
96
|
+
member_type=int,
|
|
97
|
+
serializer=IntSerializer(),
|
|
98
|
+
storage=AsyncRedisOrderedSetStorage(),
|
|
99
|
+
)
|
|
100
|
+
|
|
101
|
+
await ranking.add(client, 1, 10.0)
|
|
102
|
+
place = await ranking.rank(client, 1)
|
|
103
|
+
top = await ranking.range(client, 0, 0)
|
|
104
|
+
await ranking.remove(client, 1)
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
A trie uses the same client. The suggestion string is the text you complete. The member is stored as the payload. `search` deserializes those payloads in rank order. `limit` defaults to 10. A trie has no TTL.
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
from cachebind import IntSerializer, build_async_trie_index
|
|
111
|
+
from cachebind.storage import AsyncRedisTrieStorage
|
|
112
|
+
|
|
113
|
+
cities = build_async_trie_index(
|
|
114
|
+
"cities",
|
|
115
|
+
member_type=int,
|
|
116
|
+
serializer=IntSerializer(),
|
|
117
|
+
storage=AsyncRedisTrieStorage(),
|
|
118
|
+
)
|
|
119
|
+
|
|
120
|
+
await cities.add(client, "Paris", 1, 900.0)
|
|
121
|
+
matches = await cities.search(client, "P")
|
|
122
|
+
await cities.remove(client, "Paris")
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
`matches` is `[1]`. Redis 8 includes the suggestion commands this storage sends.
|
|
126
|
+
|
|
127
|
+
Sync indexes use `build_key_value_index`, `build_set_index`, `build_ordered_set_index`, and `build_trie_index` with the matching sync storage. Those calls are not awaited.
|
|
128
|
+
|
|
129
|
+
`get_registry` from `cachebind` returns that index: `get_registry(AsyncRedis).get("users")`.
|
|
130
|
+
|
|
131
|
+
## Install
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
pip install cachebind
|
|
135
|
+
pip install "cachebind[redis]"
|
|
136
|
+
pip install "cachebind[pydantic]"
|
|
137
|
+
pip install "cachebind[redis,pydantic]"
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
From a checkout, the same extras are:
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
pip install -e ".[dev]"
|
|
144
|
+
pip install -e ".[redis]"
|
|
145
|
+
pip install -e ".[redis,pydantic]"
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Runtime dependencies live in `pyproject.toml` under `[project] dependencies`. Optional Redis and Pydantic support, and the test tools, live in extras. A plain install does not pull Redis or Pydantic. There is no `requirements.txt`.
|
|
149
|
+
|
|
150
|
+
## Test
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
pytest
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
## Publish
|
|
157
|
+
|
|
158
|
+
When the package is ready for PyPI, build and upload it. Confirm the project name is free on PyPI first, and fill in the author details in `pyproject.toml`.
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
pip install build twine
|
|
162
|
+
python -m build
|
|
163
|
+
twine upload dist/*
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
## Documentation
|
|
167
|
+
|
|
168
|
+
- [Leaderboard](docs/leaderboard.md) — ordered set of user ids, with users loaded from Postgres
|
|
169
|
+
- [Tag-Based Caching](docs/tag-based-caching.md) — bind key-value user cache and leaderboard entry under `user:{id}`, evict together on delete
|
|
170
|
+
- [Trie (Prefix Tree)](docs/trie.md) — city names in a Redis Search trie, with cities loaded from Postgres on search
|
|
171
|
+
- [Write-Back Caching example](docs/write-back-caching.md) — collect last-visit times, then save them to the database
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# cachebind
|
|
2
|
+
|
|
3
|
+
A Python library that names a cache binding — one storage key, a serializer, and a storage — and reads or writes Python values through it.
|
|
4
|
+
|
|
5
|
+
**What is it for?** Cachebind is a way to name a cache binding and use it from application code. An index holds one storage key, a serializer, and a storage. You build it once. Each call takes your storage client and reads or writes a Python value through that binding. Redis storages are included. Any storage that matches the protocol works the same way.
|
|
6
|
+
|
|
7
|
+
**What can an index store?** A key-value index stores one model per id. A set index stores members in one set. An ordered set index stores members with scores, lowest score first. A trie index stores suggestion strings with scores and keeps each member as the payload. `search` returns those members in rank order. Each has a sync builder and an async builder.
|
|
8
|
+
|
|
9
|
+
## Indexes
|
|
10
|
+
|
|
11
|
+
Build an index once with `build_async_key_value_index`, `build_async_set_index`, `build_async_ordered_set_index`, or `build_async_trie_index`. Pass a key, the value type, a serializer instance, and a storage instance. Optionally pass `breadcrumbs` (default `ColonBreadcrumbs`) on key-value, set, and ordered-set builders. Trie indexes always use `NoopBreadcrumbs` and do not accept `breadcrumbs`. Then pass a storage client into every call.
|
|
12
|
+
|
|
13
|
+
`set` and `add` return one breadcrumb. `mset` and `madd` return one breadcrumb per item. By default, breadcrumbs encode the index key and eviction identifier. With `NoopBreadcrumbs`, writes return an empty breadcrumb. Decode a breadcrumb to get the index name and identifier, then call `evict(client, identifier)` on that index (not supported on trie indexes).
|
|
14
|
+
|
|
15
|
+
A **tag keeper** groups those breadcrumbs in Redis sets. Create `SetTagKeeper(storage=RedisSetStorage())` or `AsyncSetTagKeeper` with async set storage; optional `name` defaults to `"default"`, optional `breadcrumbs` defaults to `ColonBreadcrumbs()` for decoding on `evict`. Each logical `tag` is one set at `tag_keeper:{name}:{tag}`. After writes, call `add(client, tag, breadcrumb)` or `madd(client, tag, breadcrumbs)`; call `evict(client, tag)` to decode every breadcrumb in that set, evict through the index registry, and delete the set.
|
|
16
|
+
|
|
17
|
+
```python
|
|
18
|
+
from uuid import UUID
|
|
19
|
+
|
|
20
|
+
from pydantic import BaseModel
|
|
21
|
+
from redis.asyncio import Redis as AsyncRedis
|
|
22
|
+
|
|
23
|
+
from cachebind import build_async_key_value_index
|
|
24
|
+
from cachebind.serializers.pydantic_serializer import PydanticSerializer
|
|
25
|
+
from cachebind.storage import AsyncRedisHashStorage
|
|
26
|
+
|
|
27
|
+
class User(BaseModel):
|
|
28
|
+
id: UUID
|
|
29
|
+
name: str
|
|
30
|
+
|
|
31
|
+
ada = User(id=UUID("12345678-1234-5678-1234-567812345678"), name="Ada")
|
|
32
|
+
|
|
33
|
+
users = build_async_key_value_index(
|
|
34
|
+
"users",
|
|
35
|
+
id_type=UUID,
|
|
36
|
+
model_type=User,
|
|
37
|
+
serializer=PydanticSerializer(User),
|
|
38
|
+
storage=AsyncRedisHashStorage(),
|
|
39
|
+
)
|
|
40
|
+
|
|
41
|
+
async def main() -> None:
|
|
42
|
+
client = AsyncRedis(decode_responses=True)
|
|
43
|
+
await users.set(client, ada.id, ada, ttl=60)
|
|
44
|
+
value = await users.get(client, ada.id)
|
|
45
|
+
await users.delete(client, ada.id)
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
`ttl` is a whole number of seconds on `set` and `mset`. Omit it, or pass `None`, and the write does not expire. `mset` applies that one TTL to every id. `delete` removes one id. `mdelete` removes every given id. A missing id is not an error.
|
|
49
|
+
|
|
50
|
+
Inside `main`, the same client works for a set index.
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
from cachebind import IntSerializer, build_async_set_index
|
|
54
|
+
from cachebind.storage import AsyncRedisSetStorage
|
|
55
|
+
|
|
56
|
+
active = build_async_set_index(
|
|
57
|
+
"active_users",
|
|
58
|
+
member_type=int,
|
|
59
|
+
serializer=IntSerializer(),
|
|
60
|
+
storage=AsyncRedisSetStorage(),
|
|
61
|
+
)
|
|
62
|
+
|
|
63
|
+
await active.add(client, 1)
|
|
64
|
+
present = await active.contains(client, 1)
|
|
65
|
+
await active.remove(client, 1)
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
`remove` drops one member. A missing member is not an error. Sets have no TTL.
|
|
69
|
+
|
|
70
|
+
An ordered set uses the same client. Each member has one score. Adding a member that is already present updates its score. `rank` is 0-based, from the lowest score. `range` includes both ends. Ordered sets have no TTL.
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
from cachebind import IntSerializer, build_async_ordered_set_index
|
|
74
|
+
from cachebind.storage import AsyncRedisOrderedSetStorage
|
|
75
|
+
|
|
76
|
+
ranking = build_async_ordered_set_index(
|
|
77
|
+
"user_scores",
|
|
78
|
+
member_type=int,
|
|
79
|
+
serializer=IntSerializer(),
|
|
80
|
+
storage=AsyncRedisOrderedSetStorage(),
|
|
81
|
+
)
|
|
82
|
+
|
|
83
|
+
await ranking.add(client, 1, 10.0)
|
|
84
|
+
place = await ranking.rank(client, 1)
|
|
85
|
+
top = await ranking.range(client, 0, 0)
|
|
86
|
+
await ranking.remove(client, 1)
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
A trie uses the same client. The suggestion string is the text you complete. The member is stored as the payload. `search` deserializes those payloads in rank order. `limit` defaults to 10. A trie has no TTL.
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
from cachebind import IntSerializer, build_async_trie_index
|
|
93
|
+
from cachebind.storage import AsyncRedisTrieStorage
|
|
94
|
+
|
|
95
|
+
cities = build_async_trie_index(
|
|
96
|
+
"cities",
|
|
97
|
+
member_type=int,
|
|
98
|
+
serializer=IntSerializer(),
|
|
99
|
+
storage=AsyncRedisTrieStorage(),
|
|
100
|
+
)
|
|
101
|
+
|
|
102
|
+
await cities.add(client, "Paris", 1, 900.0)
|
|
103
|
+
matches = await cities.search(client, "P")
|
|
104
|
+
await cities.remove(client, "Paris")
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
`matches` is `[1]`. Redis 8 includes the suggestion commands this storage sends.
|
|
108
|
+
|
|
109
|
+
Sync indexes use `build_key_value_index`, `build_set_index`, `build_ordered_set_index`, and `build_trie_index` with the matching sync storage. Those calls are not awaited.
|
|
110
|
+
|
|
111
|
+
`get_registry` from `cachebind` returns that index: `get_registry(AsyncRedis).get("users")`.
|
|
112
|
+
|
|
113
|
+
## Install
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
pip install cachebind
|
|
117
|
+
pip install "cachebind[redis]"
|
|
118
|
+
pip install "cachebind[pydantic]"
|
|
119
|
+
pip install "cachebind[redis,pydantic]"
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
From a checkout, the same extras are:
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
pip install -e ".[dev]"
|
|
126
|
+
pip install -e ".[redis]"
|
|
127
|
+
pip install -e ".[redis,pydantic]"
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Runtime dependencies live in `pyproject.toml` under `[project] dependencies`. Optional Redis and Pydantic support, and the test tools, live in extras. A plain install does not pull Redis or Pydantic. There is no `requirements.txt`.
|
|
131
|
+
|
|
132
|
+
## Test
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
pytest
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
## Publish
|
|
139
|
+
|
|
140
|
+
When the package is ready for PyPI, build and upload it. Confirm the project name is free on PyPI first, and fill in the author details in `pyproject.toml`.
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
pip install build twine
|
|
144
|
+
python -m build
|
|
145
|
+
twine upload dist/*
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## Documentation
|
|
149
|
+
|
|
150
|
+
- [Leaderboard](docs/leaderboard.md) — ordered set of user ids, with users loaded from Postgres
|
|
151
|
+
- [Tag-Based Caching](docs/tag-based-caching.md) — bind key-value user cache and leaderboard entry under `user:{id}`, evict together on delete
|
|
152
|
+
- [Trie (Prefix Tree)](docs/trie.md) — city names in a Redis Search trie, with cities loaded from Postgres on search
|
|
153
|
+
- [Write-Back Caching example](docs/write-back-caching.md) — collect last-visit times, then save them to the database
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
# Leaderboard
|
|
2
|
+
|
|
3
|
+
Redis stores an ordered set named `leaderboard`. Each member is a user id. Each score is a float. Postgres stores the user rows. The index reaches Postgres only through a serializer you pass on each call.
|
|
4
|
+
|
|
5
|
+
`Serializer.serialize` and `Serializer.deserialize` are synchronous. This tutorial uses `build_ordered_set_index` and a synchronous SQLAlchemy session.
|
|
6
|
+
|
|
7
|
+
`add`, `rank`, `score`, and `remove` take a `User`. Those methods call `serialize` on the serializer you pass before they talk to Redis. Redis keeps the id string, under the key `leaderboard`.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
pip install "cachebind[redis]" "sqlalchemy>=2" "psycopg[binary]"
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Postgres and Redis for a local run:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
docker run --name cachebind-postgres -e POSTGRES_PASSWORD=cachebind -e POSTGRES_DB=cachebind -p 5432:5432 -d postgres:16
|
|
19
|
+
docker run --name cachebind-redis -p 6379:6379 -d redis:7
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
The database URL is `postgresql+psycopg://postgres:cachebind@localhost:5432/cachebind`.
|
|
23
|
+
|
|
24
|
+
## Users
|
|
25
|
+
|
|
26
|
+
`User` is a SQLAlchemy model. The primary key is a UUID. Create the table, then insert five rows.
|
|
27
|
+
|
|
28
|
+
```python
|
|
29
|
+
import uuid
|
|
30
|
+
|
|
31
|
+
from sqlalchemy import String, create_engine
|
|
32
|
+
from sqlalchemy.dialects.postgresql import UUID
|
|
33
|
+
from sqlalchemy.orm import DeclarativeBase, Mapped, Session, mapped_column, sessionmaker
|
|
34
|
+
|
|
35
|
+
class Base(DeclarativeBase):
|
|
36
|
+
pass
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
class User(Base):
|
|
40
|
+
__tablename__ = "users"
|
|
41
|
+
|
|
42
|
+
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True)
|
|
43
|
+
name: Mapped[str] = mapped_column(String)
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
engine = create_engine("postgresql+psycopg://postgres:cachebind@localhost:5432/cachebind")
|
|
47
|
+
sessions = sessionmaker(bind=engine, expire_on_commit=False)
|
|
48
|
+
Base.metadata.create_all(engine)
|
|
49
|
+
|
|
50
|
+
ada = User(id=uuid.UUID("12345678-1234-5678-1234-567812345678"), name="Ada")
|
|
51
|
+
grace = User(id=uuid.UUID("87654321-4321-8765-4321-876543218765"), name="Grace")
|
|
52
|
+
lin = User(id=uuid.UUID("11111111-1111-4111-8111-111111111111"), name="Lin")
|
|
53
|
+
maya = User(id=uuid.UUID("22222222-2222-4222-8222-222222222222"), name="Maya")
|
|
54
|
+
omar = User(id=uuid.UUID("33333333-3333-4333-8333-333333333333"), name="Omar")
|
|
55
|
+
|
|
56
|
+
with sessions.begin() as session:
|
|
57
|
+
session.add_all([ada, grace, lin, maya, omar])
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
`expire_on_commit=False` keeps `ada.id` on the instance after that session closes. `serialize` reads `value.id` on every write.
|
|
61
|
+
|
|
62
|
+
The snippets in this tutorial are one program, in this order.
|
|
63
|
+
|
|
64
|
+
## Serializer
|
|
65
|
+
|
|
66
|
+
`UserSerializer` declares `Serializer[User, str]`. The builder checks that declaration. `member_type` must be `User`, and the Redis storage member type is `str`.
|
|
67
|
+
|
|
68
|
+
`UserSerializer` takes one open `Session`. `serialize` returns `str(value.id)`. `mserialize` returns those id strings in input order. `deserialize` loads the row for the stored UUID and returns that `User`. A missing row raises `ValueError`. `mdeserialize` loads every stored id with one query. The query does not keep input order, so that method puts each `User` back in that order. `expunge` detaches each loaded `User` so its attributes stay available after the session closes.
|
|
69
|
+
|
|
70
|
+
Pass `serializer=UserSerializer(session)` on every index call that serializes or deserializes while `session` is open.
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
from collections.abc import Sequence
|
|
74
|
+
|
|
75
|
+
from sqlalchemy import select
|
|
76
|
+
|
|
77
|
+
from cachebind import Serializer
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
class UserSerializer(Serializer[User, str]):
|
|
81
|
+
def __init__(self, session: Session) -> None:
|
|
82
|
+
self.session = session
|
|
83
|
+
|
|
84
|
+
def serialize(self, value: User) -> str:
|
|
85
|
+
return str(value.id)
|
|
86
|
+
|
|
87
|
+
def deserialize(self, value: str) -> User:
|
|
88
|
+
user_id = uuid.UUID(value)
|
|
89
|
+
row = self.session.get(User, user_id)
|
|
90
|
+
if row is None:
|
|
91
|
+
raise ValueError(f"no user {user_id}")
|
|
92
|
+
self.session.expunge(row)
|
|
93
|
+
return row
|
|
94
|
+
|
|
95
|
+
def mserialize(self, values: Sequence[User]) -> list[str]:
|
|
96
|
+
return [str(value.id) for value in values]
|
|
97
|
+
|
|
98
|
+
def mdeserialize(self, values: Sequence[str]) -> list[User]:
|
|
99
|
+
ids = [uuid.UUID(value) for value in values]
|
|
100
|
+
rows = self.session.scalars(select(User).where(User.id.in_(ids))).all()
|
|
101
|
+
by_id = {row.id: row for row in rows}
|
|
102
|
+
for row in rows:
|
|
103
|
+
self.session.expunge(row)
|
|
104
|
+
loaded: list[User] = []
|
|
105
|
+
for user_id in ids:
|
|
106
|
+
row = by_id.get(user_id)
|
|
107
|
+
if row is None:
|
|
108
|
+
raise ValueError(f"no user {user_id}")
|
|
109
|
+
loaded.append(row)
|
|
110
|
+
return loaded
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
## Index
|
|
114
|
+
|
|
115
|
+
Build the index once with `NoopSerializer[User, str]()` as the default serializer on the registered class. That default does not talk to Postgres. A second build with the same key raises `ValueError`. Pass the Redis client into every call.
|
|
116
|
+
|
|
117
|
+
```python
|
|
118
|
+
from redis import Redis
|
|
119
|
+
|
|
120
|
+
from cachebind import NoopSerializer, build_ordered_set_index
|
|
121
|
+
from cachebind.storage import RedisOrderedSetStorage
|
|
122
|
+
|
|
123
|
+
leaderboard = build_ordered_set_index(
|
|
124
|
+
"leaderboard",
|
|
125
|
+
member_type=User,
|
|
126
|
+
serializer=NoopSerializer[User, str](),
|
|
127
|
+
storage=RedisOrderedSetStorage(),
|
|
128
|
+
)
|
|
129
|
+
|
|
130
|
+
client = Redis(decode_responses=True)
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## Scores
|
|
134
|
+
|
|
135
|
+
`add` stores the user id with a score. Calling `add` again for the same user replaces the score.
|
|
136
|
+
|
|
137
|
+
```python
|
|
138
|
+
with sessions() as session:
|
|
139
|
+
user_serializer = UserSerializer(session)
|
|
140
|
+
leaderboard.add(client, member=maya, score=900.0, serializer=user_serializer)
|
|
141
|
+
leaderboard.add(client, member=ada, score=1500.0, serializer=user_serializer)
|
|
142
|
+
leaderboard.add(client, member=ada, score=1800.0, serializer=user_serializer)
|
|
143
|
+
leaderboard.add(client, member=omar, score=2100.0, serializer=user_serializer)
|
|
144
|
+
leaderboard.add(client, member=grace, score=2200.0, serializer=user_serializer)
|
|
145
|
+
leaderboard.add(client, member=lin, score=2500.0, serializer=user_serializer)
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
From the lowest score to the highest, the board is Maya, Ada, Omar, Grace, Lin. `rank` counts that way, starting at `0`.
|
|
149
|
+
|
|
150
|
+
`rev_range_with_scores` counts from the highest score. Both ends are inclusive. The first three most rated users are indexes `0` through `2`. That call uses `mdeserialize`, so one query loads Lin, Grace, and Omar from Postgres.
|
|
151
|
+
|
|
152
|
+
```python
|
|
153
|
+
with sessions() as session:
|
|
154
|
+
top = leaderboard.rev_range_with_scores(
|
|
155
|
+
client,
|
|
156
|
+
start=0,
|
|
157
|
+
stop=2,
|
|
158
|
+
serializer=UserSerializer(session),
|
|
159
|
+
)
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
`top` is `[(lin, 2500.0), (grace, 2200.0), (omar, 2100.0)]`.
|
|
163
|
+
|
|
164
|
+
`rev_rank` counts from the highest score, starting at `0`.
|
|
165
|
+
|
|
166
|
+
```python
|
|
167
|
+
with sessions() as session:
|
|
168
|
+
user_serializer = UserSerializer(session)
|
|
169
|
+
place = leaderboard.rev_rank(client, lin, serializer=user_serializer)
|
|
170
|
+
points = leaderboard.score(client, lin, serializer=user_serializer)
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Lin's `rev_rank` is `0` and the score is `2500.0`. Grace is `1`. Maya is `4`. A missing user returns `None`.
|
|
174
|
+
|
|
175
|
+
`remove` drops one member. A missing member is not an error. Ordered sets have no TTL.
|
|
176
|
+
|
|
177
|
+
```python
|
|
178
|
+
with sessions() as session:
|
|
179
|
+
leaderboard.remove(client, ada, serializer=UserSerializer(session))
|
|
180
|
+
```
|