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,72 @@
1
+ """Asynchronous Redis string storage."""
2
+
3
+ from collections.abc import AsyncIterator, Mapping, Sequence
4
+
5
+ from cachebind.storage._redis import AsyncRedis, decode
6
+ from cachebind.storage.key_value.async_storage import AsyncKeyValueStorage
7
+
8
+
9
+ def _redis_key(name: str, field: str) -> str:
10
+ return f"{name}:{field}"
11
+
12
+
13
+ class AsyncRedisStringStorage(AsyncKeyValueStorage[AsyncRedis, str, str]):
14
+ """Asynchronous Redis strings. The Redis key is ``name:field``."""
15
+
16
+ async def get(self, client: AsyncRedis, name: str, field: str) -> str | None:
17
+ return decode(await client.get(_redis_key(name, field)))
18
+
19
+ async def set(
20
+ self, client: AsyncRedis, name: str, field: str, value: str, *, ttl: int | None = None
21
+ ) -> None:
22
+ key = _redis_key(name, field)
23
+ if ttl is None:
24
+ await client.set(key, value)
25
+ else:
26
+ await client.set(key, value, ex=ttl)
27
+
28
+ async def delete(self, client: AsyncRedis, name: str, field: str) -> None:
29
+ await client.delete(_redis_key(name, field))
30
+
31
+ async def mdelete(self, client: AsyncRedis, name: str, fields: Sequence[str]) -> None:
32
+ if not fields:
33
+ return
34
+ await client.delete(*(_redis_key(name, field) for field in fields))
35
+
36
+ async def exists(self, client: AsyncRedis, name: str, field: str) -> bool:
37
+ return bool(await client.exists(_redis_key(name, field)))
38
+
39
+ async def mget(self, client: AsyncRedis, name: str, fields: Sequence[str]) -> list[str | None]:
40
+ if not fields:
41
+ return []
42
+ raw = await client.mget([_redis_key(name, field) for field in fields])
43
+ return [decode(item) for item in raw]
44
+
45
+ async def mset(
46
+ self, client: AsyncRedis, name: str, items: Mapping[str, str], *, ttl: int | None = None
47
+ ) -> None:
48
+ if not items:
49
+ return
50
+ mapping = {_redis_key(name, field): value for field, value in items.items()}
51
+ if ttl is None:
52
+ await client.mset(mapping)
53
+ return
54
+ pipe = client.pipeline(transaction=True)
55
+ for key, value in mapping.items():
56
+ pipe.set(key, value, ex=ttl)
57
+ await pipe.execute()
58
+
59
+ async def swap(self, client: AsyncRedis, name: str) -> str:
60
+ raise NotImplementedError(
61
+ f"{type(self).__name__} keeps one Redis key per field and cannot swap"
62
+ )
63
+
64
+ async def drop(self, client: AsyncRedis, name: str) -> None:
65
+ raise NotImplementedError(
66
+ f"{type(self).__name__} keeps one Redis key per field and cannot drop"
67
+ )
68
+
69
+ def iter(self, client: AsyncRedis, name: str) -> AsyncIterator[tuple[str, str]]:
70
+ raise NotImplementedError(
71
+ f"{type(self).__name__} keeps one Redis key per field and cannot iter"
72
+ )
@@ -0,0 +1,76 @@
1
+ """Asynchronous key-value storage."""
2
+
3
+ from collections.abc import AsyncIterator, Hashable, Mapping, Sequence
4
+ from typing import Protocol, runtime_checkable
5
+
6
+
7
+ @runtime_checkable
8
+ class AsyncKeyValueStorage[ClientType, FieldType: Hashable, StorageType](Protocol):
9
+ """Asynchronous key-value storage.
10
+
11
+ ``client`` is the storage client for that call.
12
+ ``name`` is the storage name. ``field`` identifies one stored value.
13
+ ``ttl`` is a whole number of seconds. ``None`` means the write does not expire.
14
+ ``mset`` applies one TTL to every field.
15
+ A storage that cannot treat ``name`` as one key raises ``NotImplementedError``
16
+ from ``swap``, ``drop``, and ``iter``.
17
+ """
18
+
19
+ async def get(self, client: ClientType, name: str, field: FieldType) -> StorageType | None:
20
+ """Return the stored value, or ``None`` when the field is missing."""
21
+ ...
22
+
23
+ async def set(
24
+ self,
25
+ client: ClientType,
26
+ name: str,
27
+ field: FieldType,
28
+ value: StorageType,
29
+ *,
30
+ ttl: int | None = None,
31
+ ) -> None:
32
+ """Store ``value`` under ``field``."""
33
+ ...
34
+
35
+ async def delete(self, client: ClientType, name: str, field: FieldType) -> None:
36
+ """Remove ``field``. A missing field is not an error."""
37
+ ...
38
+
39
+ async def mdelete(self, client: ClientType, name: str, fields: Sequence[FieldType]) -> None:
40
+ """Remove every field. Missing fields are not an error."""
41
+ ...
42
+
43
+ async def exists(self, client: ClientType, name: str, field: FieldType) -> bool:
44
+ """Return whether ``field`` is present."""
45
+ ...
46
+
47
+ async def mget(
48
+ self, client: ClientType, name: str, fields: Sequence[FieldType]
49
+ ) -> list[StorageType | None]:
50
+ """Return values in input order. Missing fields are ``None``."""
51
+ ...
52
+
53
+ async def mset(
54
+ self,
55
+ client: ClientType,
56
+ name: str,
57
+ items: Mapping[FieldType, StorageType],
58
+ *,
59
+ ttl: int | None = None,
60
+ ) -> None:
61
+ """Store every item. ``ttl`` applies to each field."""
62
+ ...
63
+
64
+ async def swap(self, client: ClientType, name: str) -> str:
65
+ """Rename ``name`` aside and return the new name. A missing name still returns one."""
66
+ ...
67
+
68
+ async def drop(self, client: ClientType, name: str) -> None:
69
+ """Delete ``name``. A missing name is not an error."""
70
+ ...
71
+
72
+ def iter(
73
+ self, client: ClientType, name: str
74
+ ) -> AsyncIterator[tuple[FieldType, StorageType]]:
75
+ """Yield every field and its stored value under ``name``."""
76
+ ...
@@ -0,0 +1,73 @@
1
+ """Synchronous Redis hash storage."""
2
+
3
+ from collections.abc import Iterator, Mapping, Sequence
4
+
5
+ from cachebind.storage._redis import (
6
+ SCAN_COUNT,
7
+ Redis,
8
+ decode,
9
+ required_text,
10
+ scan_done,
11
+ swap_key,
12
+ )
13
+ from cachebind.storage.key_value.storage import KeyValueStorage
14
+
15
+
16
+ class RedisHashStorage(KeyValueStorage[Redis, str, str]):
17
+ """Synchronous Redis hashes. One instance can serve any hash name."""
18
+
19
+ def get(self, client: Redis, name: str, field: str) -> str | None:
20
+ return decode(client.hget(name, field))
21
+
22
+ def set(
23
+ self, client: Redis, name: str, field: str, value: str, *, ttl: int | None = None
24
+ ) -> None:
25
+ client.hset(name, field, value)
26
+ if ttl is not None:
27
+ client.hexpire(name, ttl, field)
28
+
29
+ def delete(self, client: Redis, name: str, field: str) -> None:
30
+ client.hdel(name, field)
31
+
32
+ def mdelete(self, client: Redis, name: str, fields: Sequence[str]) -> None:
33
+ if not fields:
34
+ return
35
+ client.hdel(name, *fields)
36
+
37
+ def exists(self, client: Redis, name: str, field: str) -> bool:
38
+ return bool(client.hexists(name, field))
39
+
40
+ def mget(self, client: Redis, name: str, fields: Sequence[str]) -> list[str | None]:
41
+ if not fields:
42
+ return []
43
+ raw_values = client.hmget(name, list(fields))
44
+ return [decode(raw) for raw in raw_values]
45
+
46
+ def mset(
47
+ self, client: Redis, name: str, items: Mapping[str, str], *, ttl: int | None = None
48
+ ) -> None:
49
+ if not items:
50
+ return
51
+ mapping = dict(items)
52
+ client.hset(name, mapping=mapping)
53
+ if ttl is not None:
54
+ client.hexpire(name, ttl, *mapping)
55
+
56
+ def swap(self, client: Redis, name: str) -> str:
57
+ return swap_key(client, name)
58
+
59
+ def drop(self, client: Redis, name: str) -> None:
60
+ client.delete(name)
61
+
62
+ def iter(
63
+ self, client: Redis, name: str, *, count: int = SCAN_COUNT
64
+ ) -> Iterator[tuple[str, str]]:
65
+ cursor: object = 0
66
+ while True:
67
+ cursor, raw = client.hscan(name, cursor=cursor, count=count)
68
+ if not isinstance(raw, dict):
69
+ raise TypeError(f"unexpected Redis hash scan type: {type(raw).__name__}")
70
+ for field, value in raw.items():
71
+ yield required_text(field), required_text(value)
72
+ if scan_done(cursor):
73
+ return
@@ -0,0 +1,72 @@
1
+ """Synchronous Redis string storage."""
2
+
3
+ from collections.abc import Iterator, Mapping, Sequence
4
+
5
+ from cachebind.storage._redis import Redis, decode
6
+ from cachebind.storage.key_value.storage import KeyValueStorage
7
+
8
+
9
+ def _redis_key(name: str, field: str) -> str:
10
+ return f"{name}:{field}"
11
+
12
+
13
+ class RedisStringStorage(KeyValueStorage[Redis, str, str]):
14
+ """Synchronous Redis strings. The Redis key is ``name:field``."""
15
+
16
+ def get(self, client: Redis, name: str, field: str) -> str | None:
17
+ return decode(client.get(_redis_key(name, field)))
18
+
19
+ def set(
20
+ self, client: Redis, name: str, field: str, value: str, *, ttl: int | None = None
21
+ ) -> None:
22
+ key = _redis_key(name, field)
23
+ if ttl is None:
24
+ client.set(key, value)
25
+ else:
26
+ client.set(key, value, ex=ttl)
27
+
28
+ def delete(self, client: Redis, name: str, field: str) -> None:
29
+ client.delete(_redis_key(name, field))
30
+
31
+ def mdelete(self, client: Redis, name: str, fields: Sequence[str]) -> None:
32
+ if not fields:
33
+ return
34
+ client.delete(*(_redis_key(name, field) for field in fields))
35
+
36
+ def exists(self, client: Redis, name: str, field: str) -> bool:
37
+ return bool(client.exists(_redis_key(name, field)))
38
+
39
+ def mget(self, client: Redis, name: str, fields: Sequence[str]) -> list[str | None]:
40
+ if not fields:
41
+ return []
42
+ raw = client.mget([_redis_key(name, field) for field in fields])
43
+ return [decode(item) for item in raw]
44
+
45
+ def mset(
46
+ self, client: Redis, name: str, items: Mapping[str, str], *, ttl: int | None = None
47
+ ) -> None:
48
+ if not items:
49
+ return
50
+ mapping = {_redis_key(name, field): value for field, value in items.items()}
51
+ if ttl is None:
52
+ client.mset(mapping)
53
+ return
54
+ pipe = client.pipeline(transaction=True)
55
+ for key, value in mapping.items():
56
+ pipe.set(key, value, ex=ttl)
57
+ pipe.execute()
58
+
59
+ def swap(self, client: Redis, name: str) -> str:
60
+ raise NotImplementedError(
61
+ f"{type(self).__name__} keeps one Redis key per field and cannot swap"
62
+ )
63
+
64
+ def drop(self, client: Redis, name: str) -> None:
65
+ raise NotImplementedError(
66
+ f"{type(self).__name__} keeps one Redis key per field and cannot drop"
67
+ )
68
+
69
+ def iter(self, client: Redis, name: str) -> Iterator[tuple[str, str]]:
70
+ raise NotImplementedError(
71
+ f"{type(self).__name__} keeps one Redis key per field and cannot iter"
72
+ )
@@ -0,0 +1,74 @@
1
+ """Synchronous key-value storage."""
2
+
3
+ from collections.abc import Hashable, Iterator, Mapping, Sequence
4
+ from typing import Protocol, runtime_checkable
5
+
6
+
7
+ @runtime_checkable
8
+ class KeyValueStorage[ClientType, FieldType: Hashable, StorageType](Protocol):
9
+ """Synchronous key-value storage.
10
+
11
+ ``client`` is the storage client for that call.
12
+ ``name`` is the storage name. ``field`` identifies one stored value.
13
+ ``ttl`` is a whole number of seconds. ``None`` means the write does not expire.
14
+ ``mset`` applies one TTL to every field.
15
+ A storage that cannot treat ``name`` as one key raises ``NotImplementedError``
16
+ from ``swap``, ``drop``, and ``iter``.
17
+ """
18
+
19
+ def get(self, client: ClientType, name: str, field: FieldType) -> StorageType | None:
20
+ """Return the stored value, or ``None`` when the field is missing."""
21
+ ...
22
+
23
+ def set(
24
+ self,
25
+ client: ClientType,
26
+ name: str,
27
+ field: FieldType,
28
+ value: StorageType,
29
+ *,
30
+ ttl: int | None = None,
31
+ ) -> None:
32
+ """Store ``value`` under ``field``."""
33
+ ...
34
+
35
+ def delete(self, client: ClientType, name: str, field: FieldType) -> None:
36
+ """Remove ``field``. A missing field is not an error."""
37
+ ...
38
+
39
+ def mdelete(self, client: ClientType, name: str, fields: Sequence[FieldType]) -> None:
40
+ """Remove every field. Missing fields are not an error."""
41
+ ...
42
+
43
+ def exists(self, client: ClientType, name: str, field: FieldType) -> bool:
44
+ """Return whether ``field`` is present."""
45
+ ...
46
+
47
+ def mget(
48
+ self, client: ClientType, name: str, fields: Sequence[FieldType]
49
+ ) -> list[StorageType | None]:
50
+ """Return values in input order. Missing fields are ``None``."""
51
+ ...
52
+
53
+ def mset(
54
+ self,
55
+ client: ClientType,
56
+ name: str,
57
+ items: Mapping[FieldType, StorageType],
58
+ *,
59
+ ttl: int | None = None,
60
+ ) -> None:
61
+ """Store every item. ``ttl`` applies to each field."""
62
+ ...
63
+
64
+ def swap(self, client: ClientType, name: str) -> str:
65
+ """Rename ``name`` aside and return the new name. A missing name still returns one."""
66
+ ...
67
+
68
+ def drop(self, client: ClientType, name: str) -> None:
69
+ """Delete ``name``. A missing name is not an error."""
70
+ ...
71
+
72
+ def iter(self, client: ClientType, name: str) -> Iterator[tuple[FieldType, StorageType]]:
73
+ """Yield every field and its stored value under ``name``."""
74
+ ...
@@ -0,0 +1,29 @@
1
+ """Ordered-set storage.
2
+
3
+ ``OrderedSetStorage`` and ``AsyncOrderedSetStorage`` do not require Redis.
4
+ Importing a Redis storage class requires the ``redis`` extra.
5
+ """
6
+
7
+ from cachebind.storage.ordered_sets.async_storage import AsyncOrderedSetStorage
8
+ from cachebind.storage.ordered_sets.storage import OrderedSetStorage
9
+
10
+ __all__ = [
11
+ "AsyncOrderedSetStorage",
12
+ "AsyncRedisOrderedSetStorage",
13
+ "OrderedSetStorage",
14
+ "RedisOrderedSetStorage",
15
+ ]
16
+
17
+
18
+ def __getattr__(name: str) -> type:
19
+ if name == "AsyncRedisOrderedSetStorage":
20
+ from cachebind.storage.ordered_sets.async_redis_ordered_set_storage import (
21
+ AsyncRedisOrderedSetStorage,
22
+ )
23
+
24
+ return AsyncRedisOrderedSetStorage
25
+ if name == "RedisOrderedSetStorage":
26
+ from cachebind.storage.ordered_sets.redis_ordered_set_storage import RedisOrderedSetStorage
27
+
28
+ return RedisOrderedSetStorage
29
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
@@ -0,0 +1,60 @@
1
+ """Decode Redis ordered-set members, scores, and ranks."""
2
+
3
+ from cachebind.storage._redis import decode
4
+
5
+
6
+ def empty_range(start: int, stop: int) -> bool:
7
+ """Return whether this inclusive rank window has no members.
8
+
9
+ Both ends must be negative, or both non-negative, and ``start`` must be past
10
+ ``stop``. Mixed signs depend on the length of the ordered set.
11
+ """
12
+ if (start >= 0) != (stop >= 0):
13
+ return False
14
+ return start > stop
15
+
16
+
17
+ def member(value: object) -> str:
18
+ decoded = decode(value)
19
+ if decoded is None:
20
+ raise TypeError("unexpected Redis member type: NoneType")
21
+ return decoded
22
+
23
+
24
+ def score_value(value: object) -> float | None:
25
+ if value is None:
26
+ return None
27
+ if isinstance(value, bytes):
28
+ value = value.decode("utf-8")
29
+ if isinstance(value, bool) or not isinstance(value, int | float | str):
30
+ raise TypeError(f"unexpected Redis score type: {type(value).__name__}")
31
+ return float(value)
32
+
33
+
34
+ def rank_value(value: object) -> int | None:
35
+ if value is None:
36
+ return None
37
+ if isinstance(value, bool) or not isinstance(value, int):
38
+ raise TypeError(f"unexpected Redis rank type: {type(value).__name__}")
39
+ return value
40
+
41
+
42
+ def members_from_range(raw: object) -> list[str]:
43
+ if not isinstance(raw, list):
44
+ raise TypeError(f"unexpected Redis range type: {type(raw).__name__}")
45
+ return [member(item) for item in raw]
46
+
47
+
48
+ def pairs_from_range(raw: object) -> list[tuple[str, float]]:
49
+ if not isinstance(raw, list):
50
+ raise TypeError(f"unexpected Redis range type: {type(raw).__name__}")
51
+ pairs: list[tuple[str, float]] = []
52
+ for item in raw:
53
+ if not isinstance(item, tuple | list) or len(item) != 2:
54
+ raise TypeError(f"unexpected Redis scored member type: {type(item).__name__}")
55
+ member_raw, score_raw = item
56
+ parsed = score_value(score_raw)
57
+ if parsed is None:
58
+ raise TypeError("unexpected Redis score type: NoneType")
59
+ pairs.append((member(member_raw), parsed))
60
+ return pairs
@@ -0,0 +1,91 @@
1
+ """Asynchronous Redis ordered-set storage."""
2
+
3
+ from collections.abc import AsyncIterator, Sequence
4
+
5
+ from cachebind.storage._redis import SCAN_COUNT, AsyncRedis, async_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.async_storage import AsyncOrderedSetStorage
14
+
15
+
16
+ class AsyncRedisOrderedSetStorage(AsyncOrderedSetStorage[AsyncRedis, str]):
17
+ """Asynchronous Redis ordered sets. ``name`` is the Redis key."""
18
+
19
+ async def add(self, client: AsyncRedis, name: str, member: str, score: float) -> None:
20
+ await client.zadd(name, {member: score})
21
+
22
+ async def madd(
23
+ self, client: AsyncRedis, name: str, members: Sequence[tuple[str, float]]
24
+ ) -> None:
25
+ if not members:
26
+ return
27
+ await client.zadd(name, {member: score for member, score in members})
28
+
29
+ async def remove(self, client: AsyncRedis, name: str, member: str) -> None:
30
+ await client.zrem(name, member)
31
+
32
+ async def mremove(self, client: AsyncRedis, name: str, members: Sequence[str]) -> None:
33
+ if not members:
34
+ return
35
+ await client.zrem(name, *members)
36
+
37
+ async def contains(self, client: AsyncRedis, name: str, member: str) -> bool:
38
+ return (await client.zscore(name, member)) is not None
39
+
40
+ async def score(self, client: AsyncRedis, name: str, member: str) -> float | None:
41
+ return score_value(await client.zscore(name, member))
42
+
43
+ async def rank(self, client: AsyncRedis, name: str, member: str) -> int | None:
44
+ return rank_value(await client.zrank(name, member))
45
+
46
+ async def range(self, client: AsyncRedis, name: str, start: int, stop: int) -> list[str]:
47
+ if empty_range(start, stop):
48
+ return []
49
+ return members_from_range(await client.zrange(name, start, stop))
50
+
51
+ async def range_with_scores(
52
+ self, client: AsyncRedis, name: str, start: int, stop: int
53
+ ) -> list[tuple[str, float]]:
54
+ if empty_range(start, stop):
55
+ return []
56
+ return pairs_from_range(await client.zrange(name, start, stop, withscores=True))
57
+
58
+ async def rev_rank(self, client: AsyncRedis, name: str, member: str) -> int | None:
59
+ return rank_value(await client.zrevrank(name, member))
60
+
61
+ async def rev_range(self, client: AsyncRedis, name: str, start: int, stop: int) -> list[str]:
62
+ if empty_range(start, stop):
63
+ return []
64
+ return members_from_range(await client.zrevrange(name, start, stop))
65
+
66
+ async def rev_range_with_scores(
67
+ self, client: AsyncRedis, name: str, start: int, stop: int
68
+ ) -> list[tuple[str, float]]:
69
+ if empty_range(start, stop):
70
+ return []
71
+ return pairs_from_range(await client.zrevrange(name, start, stop, withscores=True))
72
+
73
+ async def swap(self, client: AsyncRedis, name: str) -> str:
74
+ return await async_swap_key(client, name)
75
+
76
+ async def drop(self, client: AsyncRedis, name: str) -> None:
77
+ await client.delete(name)
78
+
79
+ async def iter(
80
+ self, client: AsyncRedis, name: str, *, count: int = SCAN_COUNT
81
+ ) -> AsyncIterator[tuple[str, float]]:
82
+ start = 0
83
+ while True:
84
+ window = await self.range_with_scores(client, name, start, start + count - 1)
85
+ if not window:
86
+ return
87
+ for member, score in window:
88
+ yield member, score
89
+ if len(window) < count:
90
+ return
91
+ start += count
@@ -0,0 +1,89 @@
1
+ """Asynchronous ordered-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 AsyncOrderedSetStorage[ClientType, MemberType: Hashable](Protocol):
9
+ """Asynchronous 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
+ async 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
+ async 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
+ async def remove(self, client: ClientType, name: str, member: MemberType) -> None:
32
+ """Remove ``member``. A missing member is not an error."""
33
+ ...
34
+
35
+ async def mremove(self, client: ClientType, name: str, members: Sequence[MemberType]) -> None:
36
+ """Remove every member. Missing members are not an error."""
37
+ ...
38
+
39
+ async def contains(self, client: ClientType, name: str, member: MemberType) -> bool:
40
+ """Return whether ``member`` is in the ordered set."""
41
+ ...
42
+
43
+ async 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
+ async 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
+ async def range(
52
+ self, client: ClientType, name: str, start: int, stop: int
53
+ ) -> list[MemberType]:
54
+ """Return members from ``start`` through ``stop``, both inclusive."""
55
+ ...
56
+
57
+ async def range_with_scores(
58
+ self, client: ClientType, name: str, start: int, stop: int
59
+ ) -> list[tuple[MemberType, float]]:
60
+ """Return members and scores from ``start`` through ``stop``, both inclusive."""
61
+ ...
62
+
63
+ async def rev_rank(self, client: ClientType, name: str, member: MemberType) -> int | None:
64
+ """Return the 0-based descending rank of ``member``, or ``None`` when it is missing."""
65
+ ...
66
+
67
+ async def rev_range(
68
+ self, client: ClientType, name: str, start: int, stop: int
69
+ ) -> list[MemberType]:
70
+ """Return members from ``start`` through ``stop``, both inclusive, highest score first."""
71
+ ...
72
+
73
+ async def rev_range_with_scores(
74
+ self, client: ClientType, name: str, start: int, stop: int
75
+ ) -> list[tuple[MemberType, float]]:
76
+ """Return members and scores from ``start`` through ``stop``, highest score first."""
77
+ ...
78
+
79
+ async def swap(self, client: ClientType, name: str) -> str:
80
+ """Rename ``name`` aside and return the new name. A missing name still returns one."""
81
+ ...
82
+
83
+ async def drop(self, client: ClientType, name: str) -> None:
84
+ """Delete ``name``. A missing name is not an error."""
85
+ ...
86
+
87
+ def iter(self, client: ClientType, name: str) -> AsyncIterator[tuple[MemberType, float]]:
88
+ """Yield every member and score stored under ``name``, lowest score first."""
89
+ ...