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.
Files changed (103) hide show
  1. cachebind-1.0.0/.gitignore +12 -0
  2. cachebind-1.0.0/LICENSE +21 -0
  3. cachebind-1.0.0/PKG-INFO +171 -0
  4. cachebind-1.0.0/README.md +153 -0
  5. cachebind-1.0.0/docs/leaderboard.md +180 -0
  6. cachebind-1.0.0/docs/tag-based-caching.md +191 -0
  7. cachebind-1.0.0/docs/trie.md +230 -0
  8. cachebind-1.0.0/docs/write-back-caching.md +60 -0
  9. cachebind-1.0.0/pyproject.toml +21 -0
  10. cachebind-1.0.0/src/cachebind/__init__.py +121 -0
  11. cachebind-1.0.0/src/cachebind/indexes/__init__.py +61 -0
  12. cachebind-1.0.0/src/cachebind/indexes/_breadcrumb.py +10 -0
  13. cachebind-1.0.0/src/cachebind/indexes/_builder.py +171 -0
  14. cachebind-1.0.0/src/cachebind/indexes/_serializer.py +17 -0
  15. cachebind-1.0.0/src/cachebind/indexes/base.py +51 -0
  16. cachebind-1.0.0/src/cachebind/indexes/evict.py +21 -0
  17. cachebind-1.0.0/src/cachebind/indexes/key_value/__init__.py +14 -0
  18. cachebind-1.0.0/src/cachebind/indexes/key_value/async_index.py +145 -0
  19. cachebind-1.0.0/src/cachebind/indexes/key_value/base.py +30 -0
  20. cachebind-1.0.0/src/cachebind/indexes/key_value/builder.py +170 -0
  21. cachebind-1.0.0/src/cachebind/indexes/key_value/index.py +142 -0
  22. cachebind-1.0.0/src/cachebind/indexes/ordered_sets/__init__.py +17 -0
  23. cachebind-1.0.0/src/cachebind/indexes/ordered_sets/async_index.py +221 -0
  24. cachebind-1.0.0/src/cachebind/indexes/ordered_sets/base.py +38 -0
  25. cachebind-1.0.0/src/cachebind/indexes/ordered_sets/builder.py +146 -0
  26. cachebind-1.0.0/src/cachebind/indexes/ordered_sets/index.py +218 -0
  27. cachebind-1.0.0/src/cachebind/indexes/registry.py +38 -0
  28. cachebind-1.0.0/src/cachebind/indexes/sets/__init__.py +14 -0
  29. cachebind-1.0.0/src/cachebind/indexes/sets/async_index.py +124 -0
  30. cachebind-1.0.0/src/cachebind/indexes/sets/base.py +24 -0
  31. cachebind-1.0.0/src/cachebind/indexes/sets/builder.py +146 -0
  32. cachebind-1.0.0/src/cachebind/indexes/sets/index.py +121 -0
  33. cachebind-1.0.0/src/cachebind/indexes/tries/__init__.py +14 -0
  34. cachebind-1.0.0/src/cachebind/indexes/tries/async_index.py +113 -0
  35. cachebind-1.0.0/src/cachebind/indexes/tries/base.py +25 -0
  36. cachebind-1.0.0/src/cachebind/indexes/tries/builder.py +141 -0
  37. cachebind-1.0.0/src/cachebind/indexes/tries/index.py +113 -0
  38. cachebind-1.0.0/src/cachebind/serializers/__init__.py +29 -0
  39. cachebind-1.0.0/src/cachebind/serializers/bool_serializer.py +21 -0
  40. cachebind-1.0.0/src/cachebind/serializers/dataclass_serializer.py +102 -0
  41. cachebind-1.0.0/src/cachebind/serializers/datetime_serializer.py +22 -0
  42. cachebind-1.0.0/src/cachebind/serializers/dict_serializer.py +29 -0
  43. cachebind-1.0.0/src/cachebind/serializers/float_serializer.py +18 -0
  44. cachebind-1.0.0/src/cachebind/serializers/int_serializer.py +20 -0
  45. cachebind-1.0.0/src/cachebind/serializers/noop_serializer.py +19 -0
  46. cachebind-1.0.0/src/cachebind/serializers/pydantic_serializer.py +29 -0
  47. cachebind-1.0.0/src/cachebind/serializers/serializer.py +24 -0
  48. cachebind-1.0.0/src/cachebind/serializers/str_serializer.py +13 -0
  49. cachebind-1.0.0/src/cachebind/serializers/uuid_serializer.py +22 -0
  50. cachebind-1.0.0/src/cachebind/storage/__init__.py +67 -0
  51. cachebind-1.0.0/src/cachebind/storage/_redis.py +80 -0
  52. cachebind-1.0.0/src/cachebind/storage/key_value/__init__.py +37 -0
  53. cachebind-1.0.0/src/cachebind/storage/key_value/async_redis_hash_storage.py +73 -0
  54. cachebind-1.0.0/src/cachebind/storage/key_value/async_redis_string_storage.py +72 -0
  55. cachebind-1.0.0/src/cachebind/storage/key_value/async_storage.py +76 -0
  56. cachebind-1.0.0/src/cachebind/storage/key_value/redis_hash_storage.py +73 -0
  57. cachebind-1.0.0/src/cachebind/storage/key_value/redis_string_storage.py +72 -0
  58. cachebind-1.0.0/src/cachebind/storage/key_value/storage.py +74 -0
  59. cachebind-1.0.0/src/cachebind/storage/ordered_sets/__init__.py +29 -0
  60. cachebind-1.0.0/src/cachebind/storage/ordered_sets/_values.py +60 -0
  61. cachebind-1.0.0/src/cachebind/storage/ordered_sets/async_redis_ordered_set_storage.py +91 -0
  62. cachebind-1.0.0/src/cachebind/storage/ordered_sets/async_storage.py +89 -0
  63. cachebind-1.0.0/src/cachebind/storage/ordered_sets/redis_ordered_set_storage.py +88 -0
  64. cachebind-1.0.0/src/cachebind/storage/ordered_sets/storage.py +85 -0
  65. cachebind-1.0.0/src/cachebind/storage/sets/__init__.py +27 -0
  66. cachebind-1.0.0/src/cachebind/storage/sets/async_redis_set_storage.py +54 -0
  67. cachebind-1.0.0/src/cachebind/storage/sets/async_storage.py +49 -0
  68. cachebind-1.0.0/src/cachebind/storage/sets/redis_set_storage.py +52 -0
  69. cachebind-1.0.0/src/cachebind/storage/sets/storage.py +49 -0
  70. cachebind-1.0.0/src/cachebind/storage/tries/__init__.py +27 -0
  71. cachebind-1.0.0/src/cachebind/storage/tries/_reply.py +20 -0
  72. cachebind-1.0.0/src/cachebind/storage/tries/_values.py +36 -0
  73. cachebind-1.0.0/src/cachebind/storage/tries/async_redis_trie_storage.py +81 -0
  74. cachebind-1.0.0/src/cachebind/storage/tries/async_storage.py +78 -0
  75. cachebind-1.0.0/src/cachebind/storage/tries/redis_trie_storage.py +79 -0
  76. cachebind-1.0.0/src/cachebind/storage/tries/storage.py +78 -0
  77. cachebind-1.0.0/src/cachebind/tagging/__init__.py +19 -0
  78. cachebind-1.0.0/src/cachebind/tagging/breadcrumbs/__init__.py +11 -0
  79. cachebind-1.0.0/src/cachebind/tagging/breadcrumbs/colon_breadcrumbs.py +20 -0
  80. cachebind-1.0.0/src/cachebind/tagging/breadcrumbs/noop_breadcrumbs.py +15 -0
  81. cachebind-1.0.0/src/cachebind/tagging/breadcrumbs/protocol.py +15 -0
  82. cachebind-1.0.0/src/cachebind/tagging/tag_keeper/__init__.py +12 -0
  83. cachebind-1.0.0/src/cachebind/tagging/tag_keeper/_keys.py +10 -0
  84. cachebind-1.0.0/src/cachebind/tagging/tag_keeper/async_set_tag_keeper.py +47 -0
  85. cachebind-1.0.0/src/cachebind/tagging/tag_keeper/protocol.py +37 -0
  86. cachebind-1.0.0/src/cachebind/tagging/tag_keeper/set_tag_keeper.py +47 -0
  87. cachebind-1.0.0/tests/test_breadcrumbs.py +34 -0
  88. cachebind-1.0.0/tests/test_index_builder.py +613 -0
  89. cachebind-1.0.0/tests/test_index_tags.py +619 -0
  90. cachebind-1.0.0/tests/test_interfaces.py +513 -0
  91. cachebind-1.0.0/tests/test_ordered_set_index_builder.py +521 -0
  92. cachebind-1.0.0/tests/test_package.py +17 -0
  93. cachebind-1.0.0/tests/test_pydantic_serializer.py +42 -0
  94. cachebind-1.0.0/tests/test_redis_hash_storage.py +187 -0
  95. cachebind-1.0.0/tests/test_redis_ordered_set_storage.py +201 -0
  96. cachebind-1.0.0/tests/test_redis_set_storage.py +123 -0
  97. cachebind-1.0.0/tests/test_redis_string_storage.py +184 -0
  98. cachebind-1.0.0/tests/test_redis_trie_storage.py +232 -0
  99. cachebind-1.0.0/tests/test_serializers.py +236 -0
  100. cachebind-1.0.0/tests/test_set_index_builder.py +376 -0
  101. cachebind-1.0.0/tests/test_tag_keeper.py +246 -0
  102. cachebind-1.0.0/tests/test_trie_index_builder.py +566 -0
  103. cachebind-1.0.0/uv.lock +277 -0
@@ -0,0 +1,12 @@
1
+ .venv/
2
+ venv/
3
+ .vscode/
4
+ __pycache__/
5
+ *.py[cod]
6
+ *.egg-info/
7
+ dist/
8
+ build/
9
+ .pytest_cache/
10
+ .mypy_cache/
11
+ .ruff_cache/
12
+ *.egg
@@ -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.
@@ -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
+ ```