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,88 @@
1
+ """Synchronous Redis ordered-set storage."""
2
+
3
+ from collections.abc import Iterator, Sequence
4
+
5
+ from cachebind.storage._redis import SCAN_COUNT, Redis, swap_key
6
+ from cachebind.storage.ordered_sets._values import (
7
+ empty_range,
8
+ members_from_range,
9
+ pairs_from_range,
10
+ rank_value,
11
+ score_value,
12
+ )
13
+ from cachebind.storage.ordered_sets.storage import OrderedSetStorage
14
+
15
+
16
+ class RedisOrderedSetStorage(OrderedSetStorage[Redis, str]):
17
+ """Synchronous Redis ordered sets. ``name`` is the Redis key."""
18
+
19
+ def add(self, client: Redis, name: str, member: str, score: float) -> None:
20
+ client.zadd(name, {member: score})
21
+
22
+ def madd(self, client: Redis, name: str, members: Sequence[tuple[str, float]]) -> None:
23
+ if not members:
24
+ return
25
+ client.zadd(name, {member: score for member, score in members})
26
+
27
+ def remove(self, client: Redis, name: str, member: str) -> None:
28
+ client.zrem(name, member)
29
+
30
+ def mremove(self, client: Redis, name: str, members: Sequence[str]) -> None:
31
+ if not members:
32
+ return
33
+ client.zrem(name, *members)
34
+
35
+ def contains(self, client: Redis, name: str, member: str) -> bool:
36
+ return client.zscore(name, member) is not None
37
+
38
+ def score(self, client: Redis, name: str, member: str) -> float | None:
39
+ return score_value(client.zscore(name, member))
40
+
41
+ def rank(self, client: Redis, name: str, member: str) -> int | None:
42
+ return rank_value(client.zrank(name, member))
43
+
44
+ def range(self, client: Redis, name: str, start: int, stop: int) -> list[str]:
45
+ if empty_range(start, stop):
46
+ return []
47
+ return members_from_range(client.zrange(name, start, stop))
48
+
49
+ def range_with_scores(
50
+ self, client: Redis, name: str, start: int, stop: int
51
+ ) -> list[tuple[str, float]]:
52
+ if empty_range(start, stop):
53
+ return []
54
+ return pairs_from_range(client.zrange(name, start, stop, withscores=True))
55
+
56
+ def rev_rank(self, client: Redis, name: str, member: str) -> int | None:
57
+ return rank_value(client.zrevrank(name, member))
58
+
59
+ def rev_range(self, client: Redis, name: str, start: int, stop: int) -> list[str]:
60
+ if empty_range(start, stop):
61
+ return []
62
+ return members_from_range(client.zrevrange(name, start, stop))
63
+
64
+ def rev_range_with_scores(
65
+ self, client: Redis, name: str, start: int, stop: int
66
+ ) -> list[tuple[str, float]]:
67
+ if empty_range(start, stop):
68
+ return []
69
+ return pairs_from_range(client.zrevrange(name, start, stop, withscores=True))
70
+
71
+ def swap(self, client: Redis, name: str) -> str:
72
+ return swap_key(client, name)
73
+
74
+ def drop(self, client: Redis, name: str) -> None:
75
+ client.delete(name)
76
+
77
+ def iter(
78
+ self, client: Redis, name: str, *, count: int = SCAN_COUNT
79
+ ) -> Iterator[tuple[str, float]]:
80
+ start = 0
81
+ while True:
82
+ window = self.range_with_scores(client, name, start, start + count - 1)
83
+ if not window:
84
+ return
85
+ yield from window
86
+ if len(window) < count:
87
+ return
88
+ start += count
@@ -0,0 +1,85 @@
1
+ """Synchronous ordered-set storage."""
2
+
3
+ from collections.abc import Hashable, Iterator, Sequence
4
+ from typing import Protocol, runtime_checkable
5
+
6
+
7
+ @runtime_checkable
8
+ class OrderedSetStorage[ClientType, MemberType: Hashable](Protocol):
9
+ """Synchronous ordered-set storage.
10
+
11
+ ``client`` is the storage client for that call.
12
+ ``name`` is the ordered set name. ``member`` is one element of that set.
13
+ Each member has one score. Adding a member that is already present updates its score.
14
+ Removing a missing member is not an error.
15
+ ``rank`` is 0-based and ascending. ``rev_rank`` is 0-based and descending.
16
+ A range includes ``start`` and ``stop``.
17
+ A storage that cannot treat ``name`` as one key raises ``NotImplementedError``
18
+ from ``swap``, ``drop``, and ``iter``.
19
+ """
20
+
21
+ def add(self, client: ClientType, name: str, member: MemberType, score: float) -> None:
22
+ """Add ``member`` with ``score``. A member that is already present gets the new score."""
23
+ ...
24
+
25
+ def madd(
26
+ self, client: ClientType, name: str, members: Sequence[tuple[MemberType, float]]
27
+ ) -> None:
28
+ """Add every member with its score. A repeated member keeps the last score."""
29
+ ...
30
+
31
+ def remove(self, client: ClientType, name: str, member: MemberType) -> None:
32
+ """Remove ``member``. A missing member is not an error."""
33
+ ...
34
+
35
+ def mremove(self, client: ClientType, name: str, members: Sequence[MemberType]) -> None:
36
+ """Remove every member. Missing members are not an error."""
37
+ ...
38
+
39
+ def contains(self, client: ClientType, name: str, member: MemberType) -> bool:
40
+ """Return whether ``member`` is in the ordered set."""
41
+ ...
42
+
43
+ def score(self, client: ClientType, name: str, member: MemberType) -> float | None:
44
+ """Return the score of ``member``, or ``None`` when it is missing."""
45
+ ...
46
+
47
+ def rank(self, client: ClientType, name: str, member: MemberType) -> int | None:
48
+ """Return the 0-based ascending rank of ``member``, or ``None`` when it is missing."""
49
+ ...
50
+
51
+ def range(self, client: ClientType, name: str, start: int, stop: int) -> list[MemberType]:
52
+ """Return members from ``start`` through ``stop``, both inclusive."""
53
+ ...
54
+
55
+ def range_with_scores(
56
+ self, client: ClientType, name: str, start: int, stop: int
57
+ ) -> list[tuple[MemberType, float]]:
58
+ """Return members and scores from ``start`` through ``stop``, both inclusive."""
59
+ ...
60
+
61
+ def rev_rank(self, client: ClientType, name: str, member: MemberType) -> int | None:
62
+ """Return the 0-based descending rank of ``member``, or ``None`` when it is missing."""
63
+ ...
64
+
65
+ def rev_range(self, client: ClientType, name: str, start: int, stop: int) -> list[MemberType]:
66
+ """Return members from ``start`` through ``stop``, both inclusive, highest score first."""
67
+ ...
68
+
69
+ def rev_range_with_scores(
70
+ self, client: ClientType, name: str, start: int, stop: int
71
+ ) -> list[tuple[MemberType, float]]:
72
+ """Return members and scores from ``start`` through ``stop``, highest score first."""
73
+ ...
74
+
75
+ def swap(self, client: ClientType, name: str) -> str:
76
+ """Rename ``name`` aside and return the new name. A missing name still returns one."""
77
+ ...
78
+
79
+ def drop(self, client: ClientType, name: str) -> None:
80
+ """Delete ``name``. A missing name is not an error."""
81
+ ...
82
+
83
+ def iter(self, client: ClientType, name: str) -> Iterator[tuple[MemberType, float]]:
84
+ """Yield every member and score stored under ``name``, lowest score first."""
85
+ ...
@@ -0,0 +1,27 @@
1
+ """Set storage.
2
+
3
+ ``SetStorage`` and ``AsyncSetStorage`` do not require Redis.
4
+ Importing a Redis storage class requires the ``redis`` extra.
5
+ """
6
+
7
+ from cachebind.storage.sets.async_storage import AsyncSetStorage
8
+ from cachebind.storage.sets.storage import SetStorage
9
+
10
+ __all__ = [
11
+ "AsyncRedisSetStorage",
12
+ "AsyncSetStorage",
13
+ "RedisSetStorage",
14
+ "SetStorage",
15
+ ]
16
+
17
+
18
+ def __getattr__(name: str) -> type:
19
+ if name == "AsyncRedisSetStorage":
20
+ from cachebind.storage.sets.async_redis_set_storage import AsyncRedisSetStorage
21
+
22
+ return AsyncRedisSetStorage
23
+ if name == "RedisSetStorage":
24
+ from cachebind.storage.sets.redis_set_storage import RedisSetStorage
25
+
26
+ return RedisSetStorage
27
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
@@ -0,0 +1,54 @@
1
+ """Asynchronous Redis set storage."""
2
+
3
+ from collections.abc import AsyncIterator, Sequence
4
+
5
+ from cachebind.storage._redis import (
6
+ SCAN_COUNT,
7
+ AsyncRedis,
8
+ async_swap_key,
9
+ required_text,
10
+ scan_done,
11
+ )
12
+ from cachebind.storage.sets.async_storage import AsyncSetStorage
13
+
14
+
15
+ class AsyncRedisSetStorage(AsyncSetStorage[AsyncRedis, str]):
16
+ """Asynchronous Redis sets. ``name`` is the Redis key."""
17
+
18
+ async def add(self, client: AsyncRedis, name: str, member: str) -> None:
19
+ await client.sadd(name, member)
20
+
21
+ async def madd(self, client: AsyncRedis, name: str, members: Sequence[str]) -> None:
22
+ if not members:
23
+ return
24
+ await client.sadd(name, *members)
25
+
26
+ async def remove(self, client: AsyncRedis, name: str, member: str) -> None:
27
+ await client.srem(name, member)
28
+
29
+ async def mremove(self, client: AsyncRedis, name: str, members: Sequence[str]) -> None:
30
+ if not members:
31
+ return
32
+ await client.srem(name, *members)
33
+
34
+ async def contains(self, client: AsyncRedis, name: str, member: str) -> bool:
35
+ return bool(await client.sismember(name, member))
36
+
37
+ async def swap(self, client: AsyncRedis, name: str) -> str:
38
+ return await async_swap_key(client, name)
39
+
40
+ async def drop(self, client: AsyncRedis, name: str) -> None:
41
+ await client.delete(name)
42
+
43
+ async def iter(
44
+ self, client: AsyncRedis, name: str, *, count: int = SCAN_COUNT
45
+ ) -> AsyncIterator[str]:
46
+ cursor: object = 0
47
+ while True:
48
+ cursor, raw = await client.sscan(name, cursor=cursor, count=count)
49
+ if not isinstance(raw, list):
50
+ raise TypeError(f"unexpected Redis set scan type: {type(raw).__name__}")
51
+ for member in raw:
52
+ yield required_text(member)
53
+ if scan_done(cursor):
54
+ return
@@ -0,0 +1,49 @@
1
+ """Asynchronous set storage."""
2
+
3
+ from collections.abc import AsyncIterator, Hashable, Sequence
4
+ from typing import Protocol, runtime_checkable
5
+
6
+
7
+ @runtime_checkable
8
+ class AsyncSetStorage[ClientType, MemberType: Hashable](Protocol):
9
+ """Asynchronous set storage.
10
+
11
+ ``client`` is the storage client for that call.
12
+ ``name`` is the set name. ``member`` is one element of that set.
13
+ Adding a member that is already present is not an error.
14
+ Removing a missing member is not an error.
15
+ A storage that cannot treat ``name`` as one key raises ``NotImplementedError``
16
+ from ``swap``, ``drop``, and ``iter``.
17
+ """
18
+
19
+ async def add(self, client: ClientType, name: str, member: MemberType) -> None:
20
+ """Add ``member`` to the set."""
21
+ ...
22
+
23
+ async def madd(self, client: ClientType, name: str, members: Sequence[MemberType]) -> None:
24
+ """Add every member."""
25
+ ...
26
+
27
+ async def remove(self, client: ClientType, name: str, member: MemberType) -> None:
28
+ """Remove ``member``. A missing member is not an error."""
29
+ ...
30
+
31
+ async def mremove(self, client: ClientType, name: str, members: Sequence[MemberType]) -> None:
32
+ """Remove every member. Missing members are not an error."""
33
+ ...
34
+
35
+ async def contains(self, client: ClientType, name: str, member: MemberType) -> bool:
36
+ """Return whether ``member`` is in the set."""
37
+ ...
38
+
39
+ async def swap(self, client: ClientType, name: str) -> str:
40
+ """Rename ``name`` aside and return the new name. A missing name still returns one."""
41
+ ...
42
+
43
+ async def drop(self, client: ClientType, name: str) -> None:
44
+ """Delete ``name``. A missing name is not an error."""
45
+ ...
46
+
47
+ def iter(self, client: ClientType, name: str) -> AsyncIterator[MemberType]:
48
+ """Yield every member stored under ``name``."""
49
+ ...
@@ -0,0 +1,52 @@
1
+ """Synchronous Redis set storage."""
2
+
3
+ from collections.abc import Iterator, Sequence
4
+
5
+ from cachebind.storage._redis import (
6
+ SCAN_COUNT,
7
+ Redis,
8
+ required_text,
9
+ scan_done,
10
+ swap_key,
11
+ )
12
+ from cachebind.storage.sets.storage import SetStorage
13
+
14
+
15
+ class RedisSetStorage(SetStorage[Redis, str]):
16
+ """Synchronous Redis sets. ``name`` is the Redis key."""
17
+
18
+ def add(self, client: Redis, name: str, member: str) -> None:
19
+ client.sadd(name, member)
20
+
21
+ def madd(self, client: Redis, name: str, members: Sequence[str]) -> None:
22
+ if not members:
23
+ return
24
+ client.sadd(name, *members)
25
+
26
+ def remove(self, client: Redis, name: str, member: str) -> None:
27
+ client.srem(name, member)
28
+
29
+ def mremove(self, client: Redis, name: str, members: Sequence[str]) -> None:
30
+ if not members:
31
+ return
32
+ client.srem(name, *members)
33
+
34
+ def contains(self, client: Redis, name: str, member: str) -> bool:
35
+ return bool(client.sismember(name, member))
36
+
37
+ def swap(self, client: Redis, name: str) -> str:
38
+ return swap_key(client, name)
39
+
40
+ def drop(self, client: Redis, name: str) -> None:
41
+ client.delete(name)
42
+
43
+ def iter(self, client: Redis, name: str, *, count: int = SCAN_COUNT) -> Iterator[str]:
44
+ cursor: object = 0
45
+ while True:
46
+ cursor, raw = client.sscan(name, cursor=cursor, count=count)
47
+ if not isinstance(raw, list):
48
+ raise TypeError(f"unexpected Redis set scan type: {type(raw).__name__}")
49
+ for member in raw:
50
+ yield required_text(member)
51
+ if scan_done(cursor):
52
+ return
@@ -0,0 +1,49 @@
1
+ """Synchronous set storage."""
2
+
3
+ from collections.abc import Hashable, Iterator, Sequence
4
+ from typing import Protocol, runtime_checkable
5
+
6
+
7
+ @runtime_checkable
8
+ class SetStorage[ClientType, MemberType: Hashable](Protocol):
9
+ """Synchronous set storage.
10
+
11
+ ``client`` is the storage client for that call.
12
+ ``name`` is the set name. ``member`` is one element of that set.
13
+ Adding a member that is already present is not an error.
14
+ Removing a missing member is not an error.
15
+ A storage that cannot treat ``name`` as one key raises ``NotImplementedError``
16
+ from ``swap``, ``drop``, and ``iter``.
17
+ """
18
+
19
+ def add(self, client: ClientType, name: str, member: MemberType) -> None:
20
+ """Add ``member`` to the set."""
21
+ ...
22
+
23
+ def madd(self, client: ClientType, name: str, members: Sequence[MemberType]) -> None:
24
+ """Add every member."""
25
+ ...
26
+
27
+ def remove(self, client: ClientType, name: str, member: MemberType) -> None:
28
+ """Remove ``member``. A missing member is not an error."""
29
+ ...
30
+
31
+ def mremove(self, client: ClientType, name: str, members: Sequence[MemberType]) -> None:
32
+ """Remove every member. Missing members are not an error."""
33
+ ...
34
+
35
+ def contains(self, client: ClientType, name: str, member: MemberType) -> bool:
36
+ """Return whether ``member`` is in the set."""
37
+ ...
38
+
39
+ def swap(self, client: ClientType, name: str) -> str:
40
+ """Rename ``name`` aside and return the new name. A missing name still returns one."""
41
+ ...
42
+
43
+ def drop(self, client: ClientType, name: str) -> None:
44
+ """Delete ``name``. A missing name is not an error."""
45
+ ...
46
+
47
+ def iter(self, client: ClientType, name: str) -> Iterator[MemberType]:
48
+ """Yield every member stored under ``name``."""
49
+ ...
@@ -0,0 +1,27 @@
1
+ """Trie storage.
2
+
3
+ ``TrieStorage`` and ``AsyncTrieStorage`` do not require Redis.
4
+ Importing a Redis storage class requires the ``redis`` extra.
5
+ """
6
+
7
+ from cachebind.storage.tries.async_storage import AsyncTrieStorage
8
+ from cachebind.storage.tries.storage import TrieStorage
9
+
10
+ __all__ = [
11
+ "AsyncRedisTrieStorage",
12
+ "AsyncTrieStorage",
13
+ "RedisTrieStorage",
14
+ "TrieStorage",
15
+ ]
16
+
17
+
18
+ def __getattr__(name: str) -> type:
19
+ if name == "AsyncRedisTrieStorage":
20
+ from cachebind.storage.tries.async_redis_trie_storage import AsyncRedisTrieStorage
21
+
22
+ return AsyncRedisTrieStorage
23
+ if name == "RedisTrieStorage":
24
+ from cachebind.storage.tries.redis_trie_storage import RedisTrieStorage
25
+
26
+ return RedisTrieStorage
27
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
@@ -0,0 +1,20 @@
1
+ """Parse an ``FT.SUGGET ... WITHPAYLOADS`` reply into payload strings."""
2
+
3
+ from cachebind.storage._redis import required_text
4
+
5
+
6
+ def payloads_from_suggestions(raw: object) -> list[str]:
7
+ """Return payloads from a flat suggestion reply of string, payload, string, payload."""
8
+ if raw is None:
9
+ return []
10
+ if not isinstance(raw, list):
11
+ raise TypeError(f"unexpected Redis suggestion type: {type(raw).__name__}")
12
+ if len(raw) % 2 != 0:
13
+ raise TypeError(f"unexpected Redis suggestion reply length: {len(raw)}")
14
+ payloads: list[str] = []
15
+ for index in range(0, len(raw), 2):
16
+ payload = raw[index + 1]
17
+ if payload is None:
18
+ raise ValueError("trie suggestion has no payload")
19
+ payloads.append(required_text(payload))
20
+ return payloads
@@ -0,0 +1,36 @@
1
+ """Decode Redis suggestion replies and build suggestion commands."""
2
+
3
+ DEFAULT_LIMIT = 10
4
+
5
+
6
+ def check_limit(limit: int) -> None:
7
+ """Raise ``ValueError`` unless ``limit`` is a positive integer."""
8
+ if isinstance(limit, bool) or not isinstance(limit, int) or limit < 1:
9
+ raise ValueError(f"trie limit must be a positive int, got {limit!r}")
10
+
11
+
12
+ def sugadd_command(
13
+ name: str, string: str, score: float, payload: str, *, increment: bool
14
+ ) -> list[object]:
15
+ """Return an ``FT.SUGADD`` command. ``INCR`` updates the score instead of replacing it."""
16
+ command: list[object] = ["FT.SUGADD", name, string, score]
17
+ if increment:
18
+ command.append("INCR")
19
+ command.extend(("PAYLOAD", payload))
20
+ return command
21
+
22
+
23
+ def sugget_command(name: str, prefix: str, *, fuzzy: bool, limit: int) -> list[object]:
24
+ """Return an ``FT.SUGGET`` command that asks for payloads, highest score first."""
25
+ check_limit(limit)
26
+ command: list[object] = ["FT.SUGGET", name, prefix, "MAX", limit, "WITHPAYLOADS"]
27
+ if fuzzy:
28
+ command.append("FUZZY")
29
+ return command
30
+
31
+
32
+ def length_value(value: object) -> int:
33
+ """Return a suggestion-dictionary length. ``bool`` is rejected."""
34
+ if isinstance(value, bool) or not isinstance(value, int):
35
+ raise TypeError(f"unexpected Redis suggestion length type: {type(value).__name__}")
36
+ return value
@@ -0,0 +1,81 @@
1
+ """Asynchronous Redis trie storage. ``name`` is one suggestion dictionary."""
2
+
3
+ from collections.abc import Sequence
4
+
5
+ from cachebind.storage._redis import AsyncRedis, async_swap_key
6
+ from cachebind.storage.tries._reply import payloads_from_suggestions
7
+ from cachebind.storage.tries._values import length_value, sugadd_command, sugget_command
8
+ from cachebind.storage.tries.async_storage import AsyncTrieStorage
9
+
10
+
11
+ class AsyncRedisTrieStorage(AsyncTrieStorage[AsyncRedis, str]):
12
+ """Asynchronous Redis Search trie. ``name`` is the suggestion-dictionary key.
13
+
14
+ Rank uses the stored score. A shorter remainder after the prefix ranks higher
15
+ than a longer suggestion with the same score. ``search`` returns payloads in that order.
16
+ """
17
+
18
+ async def add(
19
+ self,
20
+ client: AsyncRedis,
21
+ name: str,
22
+ string: str,
23
+ score: float,
24
+ payload: str,
25
+ *,
26
+ increment: bool = False,
27
+ ) -> None:
28
+ await client.execute_command(
29
+ *sugadd_command(name, string, score, payload, increment=increment)
30
+ )
31
+
32
+ async def madd(
33
+ self,
34
+ client: AsyncRedis,
35
+ name: str,
36
+ entries: Sequence[tuple[str, float, str]],
37
+ *,
38
+ increment: bool = False,
39
+ ) -> None:
40
+ if not entries:
41
+ return
42
+ pipe = client.pipeline(transaction=False)
43
+ for string, score, payload in entries:
44
+ pipe.execute_command(
45
+ *sugadd_command(name, string, score, payload, increment=increment)
46
+ )
47
+ await pipe.execute()
48
+
49
+ async def remove(self, client: AsyncRedis, name: str, string: str) -> None:
50
+ await client.execute_command("FT.SUGDEL", name, string)
51
+
52
+ async def mremove(self, client: AsyncRedis, name: str, strings: Sequence[str]) -> None:
53
+ if not strings:
54
+ return
55
+ pipe = client.pipeline(transaction=False)
56
+ for string in strings:
57
+ pipe.execute_command("FT.SUGDEL", name, string)
58
+ await pipe.execute()
59
+
60
+ async def search(
61
+ self,
62
+ client: AsyncRedis,
63
+ name: str,
64
+ prefix: str,
65
+ *,
66
+ fuzzy: bool = False,
67
+ limit: int = 10,
68
+ ) -> list[str]:
69
+ raw = await client.execute_command(
70
+ *sugget_command(name, prefix, fuzzy=fuzzy, limit=limit)
71
+ )
72
+ return payloads_from_suggestions(raw)
73
+
74
+ async def length(self, client: AsyncRedis, name: str) -> int:
75
+ return length_value(await client.execute_command("FT.SUGLEN", name))
76
+
77
+ async def swap(self, client: AsyncRedis, name: str) -> str:
78
+ return await async_swap_key(client, name)
79
+
80
+ async def drop(self, client: AsyncRedis, name: str) -> None:
81
+ await client.delete(name)
@@ -0,0 +1,78 @@
1
+ """Asynchronous trie storage."""
2
+
3
+ from collections.abc import Hashable, Sequence
4
+ from typing import Protocol, runtime_checkable
5
+
6
+
7
+ @runtime_checkable
8
+ class AsyncTrieStorage[ClientType, PayloadType: Hashable](Protocol):
9
+ """Asynchronous trie storage.
10
+
11
+ ``client`` is the storage client for that call.
12
+ ``name`` is the trie name. ``string`` is one suggestion in that trie.
13
+ Each suggestion has one score and one payload. Adding a string that is already
14
+ present replaces its score and payload, unless ``increment`` is true.
15
+ ``increment`` adds the score to the stored score. Removing a missing string is not an error.
16
+ ``search`` returns payloads in rank order. ``limit`` is the maximum number of payloads.
17
+ ``fuzzy`` requests matches within one edit of ``prefix``.
18
+ """
19
+
20
+ async def add(
21
+ self,
22
+ client: ClientType,
23
+ name: str,
24
+ string: str,
25
+ score: float,
26
+ payload: PayloadType,
27
+ *,
28
+ increment: bool = False,
29
+ ) -> None:
30
+ """Add ``string`` with ``score`` and ``payload``.
31
+
32
+ A string that is already present gets the new score and payload.
33
+ ``increment=True`` adds ``score`` to the stored score instead of replacing it.
34
+ """
35
+ ...
36
+
37
+ async def madd(
38
+ self,
39
+ client: ClientType,
40
+ name: str,
41
+ entries: Sequence[tuple[str, float, PayloadType]],
42
+ *,
43
+ increment: bool = False,
44
+ ) -> None:
45
+ """Add every suggestion. A repeated string keeps the last score and payload."""
46
+ ...
47
+
48
+ async def remove(self, client: ClientType, name: str, string: str) -> None:
49
+ """Remove ``string``. A missing string is not an error."""
50
+ ...
51
+
52
+ async def mremove(self, client: ClientType, name: str, strings: Sequence[str]) -> None:
53
+ """Remove every string. Missing strings are not an error."""
54
+ ...
55
+
56
+ async def search(
57
+ self,
58
+ client: ClientType,
59
+ name: str,
60
+ prefix: str,
61
+ *,
62
+ fuzzy: bool = False,
63
+ limit: int = 10,
64
+ ) -> list[PayloadType]:
65
+ """Return payloads for suggestions that match ``prefix``, in rank order."""
66
+ ...
67
+
68
+ async def length(self, client: ClientType, name: str) -> int:
69
+ """Return the number of suggestion strings in the trie."""
70
+ ...
71
+
72
+ async def swap(self, client: ClientType, name: str) -> str:
73
+ """Rename ``name`` aside and return the new name. A missing name still returns one."""
74
+ ...
75
+
76
+ async def drop(self, client: ClientType, name: str) -> None:
77
+ """Delete ``name``. A missing name is not an error."""
78
+ ...