django-cachex 0.13.2__tar.gz → 0.14.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 (101) hide show
  1. {django_cachex-0.13.2 → django_cachex-0.14.0}/PKG-INFO +2 -2
  2. {django_cachex-0.13.2 → django_cachex-0.14.0}/README.md +1 -1
  3. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/adapters/__init__.py +0 -6
  4. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/adapters/pipeline.py +48 -15
  5. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/adapters/protocols.py +7 -30
  6. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/adapters/redis_py.py +8 -0
  7. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/adapters/valkey_glide.py +80 -35
  8. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/adapters/valkey_py.py +98 -156
  9. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/helpers.py +12 -19
  10. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/models.py +2 -10
  11. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/queryset.py +1 -3
  12. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/views/key_add.py +2 -1
  13. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/views/key_detail.py +14 -9
  14. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/cache/__init__.py +0 -3
  15. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/cache/base.py +253 -197
  16. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/cache/database.py +83 -10
  17. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/cache/locmem.py +119 -48
  18. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/cache/resp.py +123 -60
  19. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/cache/valkey_glide.py +1 -0
  20. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/compressors/base.py +3 -0
  21. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/compressors/lz4.py +3 -2
  22. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/compressors/zstd.py +10 -2
  23. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/exceptions.py +3 -1
  24. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/orm/api.py +18 -8
  25. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/orm/apps.py +8 -2
  26. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/orm/management/commands/invalidate_orm_cache.py +5 -1
  27. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/orm/monkey_patch.py +4 -26
  28. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/orm/settings.py +10 -1
  29. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/orm/store.py +15 -10
  30. django_cachex-0.14.0/django_cachex/orm/transaction.py +95 -0
  31. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/semaphore.py +5 -13
  32. django_cachex-0.14.0/django_cachex/serializers/ormsgpack.py +41 -0
  33. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/stampede.py +5 -0
  34. django_cachex-0.14.0/django_cachex/tracking/__init__.py +1 -0
  35. django_cachex-0.14.0/django_cachex/tracking/adapter.py +485 -0
  36. django_cachex-0.14.0/django_cachex/tracking/config.py +134 -0
  37. django_cachex-0.14.0/django_cachex/tracking/listener.py +401 -0
  38. django_cachex-0.14.0/django_cachex/tracking/resp3.py +197 -0
  39. django_cachex-0.14.0/django_cachex/tracking/store.py +169 -0
  40. django_cachex-0.14.0/django_cachex/tracking/tracker.py +263 -0
  41. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/utils.py +15 -3
  42. {django_cachex-0.13.2 → django_cachex-0.14.0}/pyproject.toml +1 -1
  43. django_cachex-0.13.2/django_cachex/cache/_delegation.py +0 -163
  44. django_cachex-0.13.2/django_cachex/cache/tracking.py +0 -1045
  45. django_cachex-0.13.2/django_cachex/orm/transaction.py +0 -212
  46. django_cachex-0.13.2/django_cachex/serializers/ormsgpack.py +0 -19
  47. {django_cachex-0.13.2 → django_cachex-0.14.0}/.gitignore +0 -0
  48. {django_cachex-0.13.2 → django_cachex-0.14.0}/LICENSE +0 -0
  49. {django_cachex-0.13.2 → django_cachex-0.14.0}/LICENSE.django-redis +0 -0
  50. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/__init__.py +0 -0
  51. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/__init__.py +0 -0
  52. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/admin.py +0 -0
  53. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/apps.py +0 -0
  54. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/cas.py +0 -0
  55. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/cache/_object_tools.html +0 -0
  56. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/cache/change_form.html +0 -0
  57. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/cache/change_list.html +0 -0
  58. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/cache/styles.css +0 -0
  59. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/key/_add_object_tools.html +0 -0
  60. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/key/_key_detail_actions.html +0 -0
  61. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/key/_object_tools.html +0 -0
  62. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/key/add_form.html +0 -0
  63. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/key/change_form.html +0 -0
  64. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/key/change_list.html +0 -0
  65. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/key/key_detail_hash.html +0 -0
  66. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/key/key_detail_list.html +0 -0
  67. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/key/key_detail_opaque.html +0 -0
  68. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/key/key_detail_pagination.html +0 -0
  69. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/key/key_detail_set.html +0 -0
  70. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/key/key_detail_stream.html +0 -0
  71. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/key/key_detail_string.html +0 -0
  72. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/key/key_detail_value_input.html +0 -0
  73. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templates/admin/django_cachex/key/key_detail_zset.html +0 -0
  74. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templatetags/__init__.py +0 -0
  75. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/templatetags/django_cachex_admin.py +0 -0
  76. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/views/__init__.py +0 -0
  77. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/views/base.py +0 -0
  78. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/admin/views/cache_detail.py +0 -0
  79. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/cache/_semaphore_lua.py +0 -0
  80. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/cache/redis_py.py +0 -0
  81. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/cache/valkey_py.py +0 -0
  82. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/compressors/__init__.py +0 -0
  83. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/compressors/gzip.py +0 -0
  84. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/compressors/lzma.py +0 -0
  85. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/compressors/zlib.py +0 -0
  86. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/lock.py +0 -0
  87. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/orm/LICENSE +0 -0
  88. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/orm/__init__.py +0 -0
  89. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/orm/exceptions.py +0 -0
  90. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/orm/management/__init__.py +0 -0
  91. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/orm/management/commands/__init__.py +0 -0
  92. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/orm/utils.py +0 -0
  93. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/py.typed +0 -0
  94. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/script.py +0 -0
  95. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/serializers/__init__.py +0 -0
  96. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/serializers/base.py +0 -0
  97. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/serializers/json.py +0 -0
  98. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/serializers/msgpack.py +0 -0
  99. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/serializers/orjson.py +0 -0
  100. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/serializers/pickle.py +0 -0
  101. {django_cachex-0.13.2 → django_cachex-0.14.0}/django_cachex/types.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: django-cachex
3
- Version: 0.13.2
3
+ Version: 0.14.0
4
4
  Summary: Valkey and Redis cache backends for Django: standalone, Sentinel and Cluster topologies, sync and async APIs, and an ORM query cache
5
5
  Project-URL: Homepage, https://github.com/oliverhaas/django-cachex
6
6
  Project-URL: Documentation, https://oliverhaas.github.io/django-cachex/
@@ -86,7 +86,7 @@ CACHES = {
86
86
  - Lua scripting with `eval_script()`, with optional key-prefixing and encoding hooks.
87
87
  - Pluggable serializers (Pickle, JSON, MsgPack, ormsgpack, orjson) and compressors (Zlib, Gzip, LZ4, LZMA, Zstandard), each with a fallback chain to migrate between formats.
88
88
  - Cache stampede prevention (TTL-based XFetch).
89
- - `TrackingCache`, a local read cache over a Redis or Valkey alias, invalidated by the server's `CLIENT TRACKING` or bounded by a local TTL.
89
+ - [Client tracking](https://oliverhaas.github.io/django-cachex/latest/user-guide/client-tracking/), one option that keeps local copies of the values each process reads, kept current by the server's `CLIENT TRACKING`.
90
90
  - An opt-in [ORM cache](https://oliverhaas.github.io/django-cachex/latest/user-guide/orm-cache/), `django_cachex.orm`, that caches ORM query results per table and invalidates them on every write.
91
91
  - `LocMemCache` and `DatabaseCache` extensions with the hash, list, set and sorted set operations, `ttl()`/`expire()`/`persist()`, key patterns and admin support, but no streams, locks, pipelines or Lua.
92
92
  - Experimental `ValkeyGlideCache` and `ValkeyGlideClusterCache` backends on `valkey-glide`, Valkey's official client with a Rust core.
@@ -32,7 +32,7 @@ CACHES = {
32
32
  - Lua scripting with `eval_script()`, with optional key-prefixing and encoding hooks.
33
33
  - Pluggable serializers (Pickle, JSON, MsgPack, ormsgpack, orjson) and compressors (Zlib, Gzip, LZ4, LZMA, Zstandard), each with a fallback chain to migrate between formats.
34
34
  - Cache stampede prevention (TTL-based XFetch).
35
- - `TrackingCache`, a local read cache over a Redis or Valkey alias, invalidated by the server's `CLIENT TRACKING` or bounded by a local TTL.
35
+ - [Client tracking](https://oliverhaas.github.io/django-cachex/latest/user-guide/client-tracking/), one option that keeps local copies of the values each process reads, kept current by the server's `CLIENT TRACKING`.
36
36
  - An opt-in [ORM cache](https://oliverhaas.github.io/django-cachex/latest/user-guide/orm-cache/), `django_cachex.orm`, that caches ORM query results per table and invalidates them on every write.
37
37
  - `LocMemCache` and `DatabaseCache` extensions with the hash, list, set and sorted set operations, `ttl()`/`expire()`/`persist()`, key patterns and admin support, but no streams, locks, pipelines or Lua.
38
38
  - Experimental `ValkeyGlideCache` and `ValkeyGlideClusterCache` backends on `valkey-glide`, Valkey's official client with a Rust core.
@@ -12,8 +12,6 @@ from typing import TYPE_CHECKING, Any
12
12
  if TYPE_CHECKING:
13
13
  from django_cachex.adapters.pipeline import AsyncPipeline, Pipeline
14
14
  from django_cachex.adapters.protocols import (
15
- Invalidation,
16
- InvalidationListenerProtocol,
17
15
  RespAdapterProtocol,
18
16
  RespAsyncPipelineProtocol,
19
17
  RespPipelineProtocol,
@@ -43,8 +41,6 @@ if TYPE_CHECKING:
43
41
  _LAZY_EXPORTS = {
44
42
  "AsyncPipeline": "django_cachex.adapters.pipeline",
45
43
  "Pipeline": "django_cachex.adapters.pipeline",
46
- "Invalidation": "django_cachex.adapters.protocols",
47
- "InvalidationListenerProtocol": "django_cachex.adapters.protocols",
48
44
  "RespAdapterProtocol": "django_cachex.adapters.protocols",
49
45
  "RespAsyncPipelineProtocol": "django_cachex.adapters.protocols",
50
46
  "RespPipelineProtocol": "django_cachex.adapters.protocols",
@@ -82,8 +78,6 @@ def __dir__() -> list[str]:
82
78
 
83
79
  __all__ = [
84
80
  "AsyncPipeline",
85
- "Invalidation",
86
- "InvalidationListenerProtocol",
87
81
  "Pipeline",
88
82
  "RedisPyAdapter",
89
83
  "RedisPyAsyncPipelineAdapter",
@@ -26,6 +26,8 @@ if TYPE_CHECKING:
26
26
  from django_cachex.adapters.protocols import RespAsyncPipelineProtocol, RespPipelineProtocol
27
27
  from django_cachex.stampede import StampedeConfig
28
28
 
29
+ from django_cachex.adapters.valkey_py import _decode_xpending
30
+ from django_cachex.cache.resp import _STAMPEDE_ADD_LUA, _STAMPEDE_SET_LUA
29
31
  from django_cachex.exceptions import KeyNotFoundError, NotSupportedError, maybe_wrap_set_nx_get, translate_server_error
30
32
  from django_cachex.script import ScriptHelpers, reject_stray_encoded
31
33
  from django_cachex.types import KeyType
@@ -34,6 +36,7 @@ from django_cachex.utils import (
34
36
  _validate_linsert_where,
35
37
  _validate_lpos_args,
36
38
  _validate_pop_count,
39
+ _validate_set_flags,
37
40
  _validate_zadd_flags,
38
41
  _validate_zrange_limit,
39
42
  _wire_key,
@@ -218,11 +221,11 @@ class Pipeline:
218
221
 
219
222
  def _decode_hash_keys(self, value: list[bytes]) -> list[str]:
220
223
  """Decode hash field names (keys are not serialized, just bytes)."""
221
- return [k.decode() for k in value]
224
+ return [k.decode(errors="surrogateescape") for k in value]
222
225
 
223
226
  def _decode_hash_dict(self, value: dict[bytes, bytes]) -> dict[str, Any]:
224
227
  """Decode a full hash (keys are strings, values are decoded)."""
225
- return {k.decode(): self._cache.decode(v) for k, v in value.items()}
228
+ return {k.decode(errors="surrogateescape"): self._cache.decode(v) for k, v in value.items()}
226
229
 
227
230
  def _decode_zset_with_scores(self, value: list[tuple[bytes, float]]) -> list[tuple[Any, float]]:
228
231
  """Decode sorted set members with scores."""
@@ -283,7 +286,10 @@ class Pipeline:
283
286
  return [
284
287
  (
285
288
  entry_id.decode() if isinstance(entry_id, bytes) else entry_id,
286
- {k.decode() if isinstance(k, bytes) else k: self._cache.decode(v) for k, v in (fields or {}).items()},
289
+ {
290
+ k.decode(errors="surrogateescape") if isinstance(k, bytes) else k: self._cache.decode(v)
291
+ for k, v in (fields or {}).items()
292
+ },
287
293
  )
288
294
  for entry_id, fields in results
289
295
  ]
@@ -368,16 +374,22 @@ class Pipeline:
368
374
  Decodes to ``True`` when the write ran and ``False`` on an ``nx`` /
369
375
  ``xx`` miss, like :meth:`RespCache.set` with those flags. With
370
376
  ``get=True`` it decodes to the previous value instead (``None`` when
371
- the key was absent), again like :meth:`RespCache.set`.
377
+ the key was absent), again like :meth:`RespCache.set`. With stampede
378
+ prevention active, the flags count a key inside the buffer as absent,
379
+ and ``nx`` and ``xx`` together raise ``ValueError``, as there.
372
380
  """
381
+ _validate_set_flags(nx=nx, xx=xx)
373
382
  nkey = self._make_key(key, version)
383
+ buffer_s = self._cache._stampede_buffer(stampede_prevention) if nx or xx or get else None
384
+ if buffer_s is not None:
385
+ return self._set_with_buffer(nkey, value, timeout, buffer_s, stampede_prevention, nx=nx, xx=xx, get=get)
374
386
  nvalue = self._encode(value)
375
387
  # Normalize before buffering, same order as RespCache.set()/touch().
376
388
  backend_timeout = self._cache.get_backend_timeout(timeout)
377
389
  actual_timeout = self._adapter.get_timeout_with_buffer(backend_timeout, stampede_prevention)
378
390
 
379
391
  # Immediate expiry: queue the net effect of a SET-with-flags whose key expires on arrival.
380
- if actual_timeout == 0 and not (nx and xx):
392
+ if actual_timeout == 0:
381
393
  if get:
382
394
  # SET GET hands back the old value; the key is gone afterwards
383
395
  # unless NX left an existing one untouched.
@@ -396,24 +408,45 @@ class Pipeline:
396
408
  self._decoders.append(bool if xx else (lambda _result: True))
397
409
  return self
398
410
 
399
- kwargs: dict[str, Any] = {}
400
- # nx and xx together fall through so the driver raises its own error.
411
+ kwargs: dict[str, Any] = {flag: True for flag, on in (("nx", nx), ("xx", xx), ("get", get)) if on}
401
412
  if actual_timeout:
402
413
  kwargs["ex"] = actual_timeout
403
- if nx:
404
- kwargs["nx"] = True
405
- if xx:
406
- kwargs["xx"] = True
407
- if get:
408
- kwargs["get"] = True
409
414
 
410
415
  self._pipeline_adapter.set(nkey, nvalue, **kwargs)
411
- if nx and get and not xx:
416
+ if nx and get:
412
417
  self._decoders.append(_ErrorAware(self._decode_set_nx_get))
413
418
  else:
414
419
  self._decoders.append(self._decode_single if get else bool)
415
420
  return self
416
421
 
422
+ def _set_with_buffer(
423
+ self,
424
+ nkey: str,
425
+ value: Any,
426
+ timeout: float | None,
427
+ buffer_s: int,
428
+ stampede_prevention: bool | StampedeConfig | None,
429
+ *,
430
+ nx: bool,
431
+ xx: bool,
432
+ get: bool,
433
+ ) -> Self:
434
+ """Queue a flagged ``set()`` through the scripts :meth:`RespCache.set` runs, so a key inside the buffer counts as absent."""
435
+ if nx and not get:
436
+ timeout_s = self._adapter.get_timeout_with_buffer(
437
+ self._cache.get_backend_timeout(timeout),
438
+ stampede_prevention,
439
+ )
440
+ timeout_arg = -1 if timeout_s is None else timeout_s
441
+ nvalue = self._encode(value)
442
+ self._pipeline_adapter.execute_command("EVAL", _STAMPEDE_ADD_LUA, 1, nkey, nvalue, timeout_arg, buffer_s)
443
+ self._decoders.append(bool)
444
+ return self
445
+ argv = self._cache._stampede_set_argv(value, timeout, buffer_s, stampede_prevention, nx=nx, xx=xx, get=get)
446
+ self._pipeline_adapter.execute_command("EVAL", _STAMPEDE_SET_LUA, 1, nkey, *argv)
447
+ self._decoders.append(_ErrorAware(self._decode_set_nx_get) if nx else self._decode_single if get else bool)
448
+ return self
449
+
417
450
  def get(self, key: str, default: Any = None, version: int | None = None) -> Self:
418
451
  """Queue a GET command. Decodes to ``default`` for a missing key, like :meth:`RespCache.get`."""
419
452
  nkey = self._make_key(key, version)
@@ -1957,7 +1990,7 @@ class Pipeline:
1957
1990
  )
1958
1991
  else:
1959
1992
  self._pipeline_adapter.xpending(nkey, group)
1960
- self._decoders.append(self._noop)
1993
+ self._decoders.append(_decode_xpending)
1961
1994
  return self
1962
1995
 
1963
1996
  def xclaim(
@@ -17,7 +17,7 @@ pipeline layers rely on.
17
17
  driver's real implementations.
18
18
  """
19
19
 
20
- from typing import TYPE_CHECKING, Any, NamedTuple, Protocol, runtime_checkable
20
+ from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
21
21
 
22
22
  if TYPE_CHECKING:
23
23
  from collections.abc import AsyncIterator, Iterator, Mapping, Sequence
@@ -31,24 +31,6 @@ if TYPE_CHECKING:
31
31
  _set = set
32
32
 
33
33
 
34
- class Invalidation(NamedTuple):
35
- """One CLIENT TRACKING message: the made keys to drop, or ``None`` after ``FLUSHDB``/``FLUSHALL``."""
36
-
37
- keys: tuple[str, ...] | None
38
-
39
-
40
- @runtime_checkable
41
- class InvalidationListenerProtocol(Protocol):
42
- """A live CLIENT TRACKING BCAST subscription; any exception from ``poll``/``ping`` means it is lost."""
43
-
44
- # Server-side id of the tracking connection, for diagnostics and tests.
45
- client_id: int
46
-
47
- def poll(self, timeout: float) -> Invalidation | None: ...
48
- def ping(self) -> None: ...
49
- def close(self) -> None: ...
50
-
51
-
52
34
  class _RespPipelineCommandsProtocol(Protocol):
53
35
  """Shared chainable-command surface for sync/async pipeline protocols.
54
36
 
@@ -543,8 +525,8 @@ class RespAdapterProtocol(Protocol):
543
525
  *,
544
526
  stampede_prevention: bool | StampedeConfig | None = None,
545
527
  ) -> dict[str, bytes]: ...
546
- def has_key(self, key: str) -> bool: ...
547
- async def ahas_key(self, key: str) -> bool: ...
528
+ def has_key(self, key: str, *, stampede_prevention: bool | StampedeConfig | None = None) -> bool: ...
529
+ async def ahas_key(self, key: str, *, stampede_prevention: bool | StampedeConfig | None = None) -> bool: ...
548
530
  def type(self, key: str) -> KeyType | None: ...
549
531
  async def atype(self, key: str) -> KeyType | None: ...
550
532
  # MEMORY USAGE: bytes for the key and its value, None for a missing key.
@@ -637,13 +619,10 @@ class RespAdapterProtocol(Protocol):
637
619
  ) -> Any: ...
638
620
  def pipeline(self, *, transaction: bool = True) -> RespPipelineProtocol: ...
639
621
  async def apipeline(self, *, transaction: bool = True) -> RespAsyncPipelineProtocol: ...
640
- # CLIENT TRACKING BCAST subscription on the primary; NotSupportedError where the driver cannot host one.
641
- def invalidation_listener(
642
- self,
643
- prefixes: Sequence[str],
644
- *,
645
- timeout: float = 5.0,
646
- ) -> InvalidationListenerProtocol: ...
622
+ # A new RESP3 connection to the primary for client tracking; NotSupportedError where the driver cannot host one.
623
+ def tracking_connection(self) -> Any: ...
624
+ # The primary's address as the Sentinels name it now; None without Sentinel.
625
+ def tracking_primary(self) -> tuple[str, int] | None: ...
647
626
  def info(self, section: str | None = None) -> dict[str, Any]: ...
648
627
  def slowlog_get(self, count: int = 10) -> list[dict[str, Any]]: ...
649
628
  def slowlog_len(self) -> int: ...
@@ -1237,8 +1216,6 @@ class RespAdapterProtocol(Protocol):
1237
1216
 
1238
1217
 
1239
1218
  __all__ = [
1240
- "Invalidation",
1241
- "InvalidationListenerProtocol",
1242
1219
  "RespAdapterProtocol",
1243
1220
  "RespAsyncPipelineProtocol",
1244
1221
  "RespPipelineProtocol",
@@ -87,6 +87,14 @@ class _RedisPyMixin:
87
87
  def _missing_lib_error() -> ImportError:
88
88
  return _missing_redis()
89
89
 
90
+ def _tracking_connection_kwargs(self, kwargs: dict[str, Any]) -> dict[str, Any]:
91
+ # Maintenance notifications would read pushes on the tracking socket.
92
+ if "maint_notifications_config" in kwargs or "maint_notifications_pool_handler" in kwargs:
93
+ kwargs.pop("maint_notifications_pool_handler", None)
94
+ kwargs.pop("oss_cluster_maint_notifications_handler", None)
95
+ kwargs["maint_notifications_config"] = None
96
+ return kwargs
97
+
90
98
 
91
99
  # redis-py and valkey-py share an identical pipeline API surface; alias
92
100
  # directly rather than carry empty subclasses.
@@ -30,7 +30,6 @@ from urllib.parse import parse_qs, unquote, urlparse
30
30
  from django.core.exceptions import ImproperlyConfigured
31
31
 
32
32
  from django_cachex.adapters.protocols import (
33
- InvalidationListenerProtocol,
34
33
  RespAdapterProtocol,
35
34
  RespAsyncPipelineProtocol,
36
35
  RespPipelineProtocol,
@@ -56,6 +55,7 @@ from django_cachex.stampede import (
56
55
  StampedeConfig,
57
56
  get_timeout_with_buffer,
58
57
  make_stampede_config,
58
+ outlives_buffer,
59
59
  resolve_stampede,
60
60
  should_recompute,
61
61
  )
@@ -64,7 +64,7 @@ from django_cachex.utils import _validate_zadd_flags, _validate_zrange_limit
64
64
 
65
65
  if TYPE_CHECKING:
66
66
  import datetime
67
- from collections.abc import Iterable, Iterator, Mapping, Sequence
67
+ from collections.abc import Generator, Iterable, Iterator, Mapping, Sequence
68
68
 
69
69
 
70
70
  # valkey-glide is an optional install: the names below stay unbound without it,
@@ -99,6 +99,8 @@ try:
99
99
  Script,
100
100
  ServerCredentials,
101
101
  )
102
+ from glide_sync import ConnectionError as GlideConnectionError # ty: ignore[unresolved-import]
103
+ from glide_sync import TimeoutError as GlideTimeoutError # ty: ignore[unresolved-import]
102
104
  from glide_sync.glide_client import GlideClient # ty: ignore[unresolved-import]
103
105
  except ImportError as _exc:
104
106
  _GLIDE_IMPORT_ERROR: ImportError | None = _exc
@@ -284,10 +286,21 @@ _TCP_SCHEMES = frozenset({"redis", "valkey", *_TLS_SCHEMES})
284
286
  _SOCKET_SCHEMES = frozenset({"unix", "redis+socket", "valkey+socket"})
285
287
 
286
288
 
289
+ def _int_option(options: dict[str, Any], name: str) -> int | None:
290
+ """OPTIONS ``name`` as an int, or None when it is unset."""
291
+ if (value := options.get(name)) is None:
292
+ return None
293
+ try:
294
+ return int(value)
295
+ except TypeError, ValueError:
296
+ msg = f"OPTIONS[{name!r}] must be an int, not {value!r}."
297
+ raise ImproperlyConfigured(msg) from None
298
+
299
+
287
300
  def _parse_db(u: Any, options: dict[str, Any]) -> int | None:
288
301
  """Database index: OPTIONS ``db`` beats the URL query, which beats the URL path."""
289
- if (db := options.get("db")) is not None:
290
- return int(db)
302
+ if (db := _int_option(options, "db")) is not None:
303
+ return db
291
304
  query_db = parse_qs(u.query).get("db")
292
305
  if query_db and query_db[-1].isdigit():
293
306
  return int(query_db[-1])
@@ -406,8 +419,8 @@ def _glide_config_kwargs(
406
419
  # natively, falling back to the primary when none is reachable.
407
420
  kwargs["read_from"] = ReadFrom.PREFER_REPLICA
408
421
 
409
- if (request_timeout := options.get("request_timeout")) is not None:
410
- kwargs["request_timeout"] = int(request_timeout)
422
+ if (request_timeout := _int_option(options, "request_timeout")) is not None:
423
+ kwargs["request_timeout"] = request_timeout
411
424
  if (client_name := options.get("client_name")) is not None:
412
425
  kwargs["client_name"] = client_name
413
426
  return kwargs
@@ -614,8 +627,8 @@ def _normalize_ttl(result: int) -> int | None:
614
627
 
615
628
 
616
629
  def _dec_str(v: Any) -> str:
617
- """Decode bytes to str; pass through anything else."""
618
- return v.decode("utf-8") if isinstance(v, (bytes, bytearray)) else v
630
+ """Decode bytes to str, invalid UTF-8 with ``surrogateescape``; pass through anything else."""
631
+ return v.decode("utf-8", "surrogateescape") if isinstance(v, (bytes, bytearray)) else v
619
632
 
620
633
 
621
634
  def _dec_keys(values: Iterable[Any]) -> list[str]:
@@ -757,7 +770,7 @@ class ValkeyGlidePipelineAdapter(RespPipelineProtocol):
757
770
 
758
771
  def __init__(
759
772
  self,
760
- client: GlideClient,
773
+ client: Any,
761
774
  *,
762
775
  transaction: bool = False,
763
776
  batch_factory: Any = None,
@@ -1698,6 +1711,8 @@ class ValkeyGlideAdapter(RespAdapterProtocol):
1698
1711
  # glide multiplexes: one connection carries every command of a client.
1699
1712
  multiplexed: bool = True
1700
1713
 
1714
+ _standalone: bool = True
1715
+
1701
1716
  def __init__(self, servers: list[str], **options: Any) -> None:
1702
1717
  _check_installed()
1703
1718
  if not servers:
@@ -1708,6 +1723,8 @@ class ValkeyGlideAdapter(RespAdapterProtocol):
1708
1723
  )
1709
1724
  raise ImproperlyConfigured(msg)
1710
1725
  _hostports(servers)
1726
+ # Build the config once, so a bad setting fails here and not at the first command.
1727
+ _glide_config_kwargs(servers, options, credentials_cls=ServerCredentials, standalone=self._standalone)
1711
1728
  self._servers = servers
1712
1729
  self._options = options
1713
1730
  self._stampede_config: StampedeConfig | None = make_stampede_config(options.get("stampede_prevention"))
@@ -1843,7 +1860,7 @@ class ValkeyGlideAdapter(RespAdapterProtocol):
1843
1860
  return await client.custom_command(args)
1844
1861
 
1845
1862
  @contextlib.contextmanager
1846
- def _blocking_client(self, block_seconds: float) -> Iterator[Any]:
1863
+ def _blocking_client(self, block_seconds: float) -> Generator[Any]:
1847
1864
  """Lend an idle client whose request timeout outlasts ``block_seconds``.
1848
1865
 
1849
1866
  Glide multiplexes each client over one connection, so a command that
@@ -1859,14 +1876,21 @@ class ValkeyGlideAdapter(RespAdapterProtocol):
1859
1876
  client = idle.pop() if idle else None
1860
1877
  if client is None:
1861
1878
  client = _WrongTypeClient(self._create_client(request_timeout=timeout))
1879
+ reusable = False
1862
1880
  try:
1863
1881
  yield client
1864
- except BaseException:
1865
- # The reply can still be on its way, so the connection can't be reused.
1866
- client.close()
1882
+ reusable = True
1883
+ except Exception as exc:
1884
+ # A server error answers the request. After a timeout, a lost connection
1885
+ # or an interrupt the reply can still be on its way.
1886
+ reusable = not isinstance(exc, (GlideTimeoutError, GlideConnectionError, ClosingError))
1867
1887
  raise
1868
- with _GLIDE_SYNC_BLOCKING_LOCK:
1869
- _GLIDE_SYNC_BLOCKING_CLIENTS.setdefault(key, []).append(client)
1888
+ finally:
1889
+ if reusable:
1890
+ with _GLIDE_SYNC_BLOCKING_LOCK:
1891
+ _GLIDE_SYNC_BLOCKING_CLIENTS.setdefault(key, []).append(client)
1892
+ else:
1893
+ client.close()
1870
1894
 
1871
1895
  def _blocking_cmd(self, args: list[Any], block_seconds: float) -> Any:
1872
1896
  with self._blocking_client(block_seconds) as client:
@@ -1896,7 +1920,10 @@ class ValkeyGlideAdapter(RespAdapterProtocol):
1896
1920
  ) -> bool:
1897
1921
  client = self._client()
1898
1922
  actual_timeout = self.get_timeout_with_buffer(timeout, stampede_prevention)
1899
- kw = {"conditional_set": ConditionalChange.ONLY_IF_DOES_NOT_EXIST, **_set_expiry(actual_timeout)}
1923
+ kw: dict[str, Any] = {
1924
+ "conditional_set": ConditionalChange.ONLY_IF_DOES_NOT_EXIST,
1925
+ **_set_expiry(actual_timeout),
1926
+ }
1900
1927
  return _ok_to_bool(client.set(key, _enc(value), **kw))
1901
1928
 
1902
1929
  def get(self, key: str, *, stampede_prevention: bool | StampedeConfig | None = None) -> Any:
@@ -1986,8 +2013,11 @@ class ValkeyGlideAdapter(RespAdapterProtocol):
1986
2013
 
1987
2014
  return found
1988
2015
 
1989
- def has_key(self, key: str) -> bool:
1990
- return bool(self._client().exists([key]))
2016
+ def has_key(self, key: str, *, stampede_prevention: bool | StampedeConfig | None = None) -> bool:
2017
+ config = self.resolve_stampede(stampede_prevention)
2018
+ if config is None:
2019
+ return bool(self._client().exists([key]))
2020
+ return outlives_buffer(self._client().ttl(key), config)
1991
2021
 
1992
2022
  def type(self, key: str) -> KeyType | None:
1993
2023
  result: Any = self._client().type(key)
@@ -2047,9 +2077,12 @@ class ValkeyGlideAdapter(RespAdapterProtocol):
2047
2077
  del kwargs
2048
2078
  self._sweep_async_clients()
2049
2079
 
2050
- def invalidation_listener(self, prefixes: Sequence[str], *, timeout: float = 5.0) -> InvalidationListenerProtocol:
2051
- """Not offered: glide's push handler drops RESP3 ``invalidate`` frames."""
2052
- raise NotSupportedError("invalidation_listener", "valkey-glide")
2080
+ def tracking_connection(self) -> Any:
2081
+ """Not offered: glide gives no access to a raw connection."""
2082
+ raise NotSupportedError("tracking_connection", "valkey-glide")
2083
+
2084
+ def tracking_primary(self) -> tuple[str, int] | None:
2085
+ raise NotSupportedError("tracking_primary", "valkey-glide")
2053
2086
 
2054
2087
  # ---- TTL ----
2055
2088
  def ttl(self, key: str) -> int | None:
@@ -2107,8 +2140,7 @@ class ValkeyGlideAdapter(RespAdapterProtocol):
2107
2140
  if count is None:
2108
2141
  count = self._default_scan_itersize
2109
2142
  result = self._client().scan(_enc(cursor), match=match, count=count, type=_object_type(_type))
2110
- keys = [k.decode(errors="surrogateescape") if isinstance(k, bytes) else k for k in result[1]]
2111
- return int(_dec_str(result[0])), keys
2143
+ return int(_dec_str(result[0])), _dec_keys(result[1])
2112
2144
 
2113
2145
  def iter_keys(self, pattern: str, itersize: int | None = None) -> Iterator[str]:
2114
2146
  for k in self._scan_keys(pattern, itersize):
@@ -2178,10 +2210,10 @@ class ValkeyGlideAdapter(RespAdapterProtocol):
2178
2210
 
2179
2211
  def hgetall(self, key: str) -> dict[str, Any]:
2180
2212
  result = self._client().hgetall(key)
2181
- return {k.decode() if isinstance(k, bytes) else k: v for k, v in result.items()}
2213
+ return {_dec_str(k): v for k, v in result.items()}
2182
2214
 
2183
2215
  def hkeys(self, key: str) -> list[str]:
2184
- return [k.decode() if isinstance(k, bytes) else k for k in self._client().hkeys(key)]
2216
+ return [_dec_str(k) for k in self._client().hkeys(key)]
2185
2217
 
2186
2218
  def hvals(self, key: str) -> list[Any]:
2187
2219
  return list(self._client().hvals(key))
@@ -2862,15 +2894,20 @@ class ValkeyGlideAdapter(RespAdapterProtocol):
2862
2894
 
2863
2895
  def slowlog_get(self, count: int = 10) -> list[dict[str, Any]]:
2864
2896
  raw = self._cmd([b"SLOWLOG", b"GET", str(count).encode()])
2897
+
2898
+ def decode(value: Any) -> Any:
2899
+ # The arguments carry serialized values, as on valkey-py.
2900
+ return value.decode("utf-8", errors="replace") if isinstance(value, bytes) else value
2901
+
2865
2902
  # Reshape each row into the dict form the other adapters return.
2866
2903
  return [
2867
2904
  {
2868
2905
  "id": entry[0],
2869
2906
  "start_time": entry[1],
2870
2907
  "duration": entry[2],
2871
- "command": [_dec_str(arg) for arg in (entry[3] or [])],
2872
- "client_address": _dec_str(entry[4]) if len(entry) > 4 else None,
2873
- "client_name": _dec_str(entry[5]) if len(entry) > 5 else None,
2908
+ "command": [decode(arg) for arg in (entry[3] or [])],
2909
+ "client_address": decode(entry[4]) if len(entry) > 4 else None,
2910
+ "client_name": decode(entry[5]) if len(entry) > 5 else None,
2874
2911
  }
2875
2912
  for entry in (raw or [])
2876
2913
  if isinstance(entry, (list, tuple)) and len(entry) >= 4
@@ -2938,7 +2975,10 @@ class ValkeyGlideAdapter(RespAdapterProtocol):
2938
2975
  ) -> bool:
2939
2976
  client = await self.get_async_client()
2940
2977
  actual_timeout = self.get_timeout_with_buffer(timeout, stampede_prevention)
2941
- kw = {"conditional_set": ConditionalChange.ONLY_IF_DOES_NOT_EXIST, **_set_expiry(actual_timeout)}
2978
+ kw: dict[str, Any] = {
2979
+ "conditional_set": ConditionalChange.ONLY_IF_DOES_NOT_EXIST,
2980
+ **_set_expiry(actual_timeout),
2981
+ }
2942
2982
  return _ok_to_bool(await client.set(key, _enc(value), **kw))
2943
2983
 
2944
2984
  async def aget(self, key: str, *, stampede_prevention: bool | StampedeConfig | None = None) -> Any:
@@ -3026,8 +3066,12 @@ class ValkeyGlideAdapter(RespAdapterProtocol):
3026
3066
 
3027
3067
  return found
3028
3068
 
3029
- async def ahas_key(self, key: str) -> bool:
3030
- return bool(await (await self.get_async_client()).exists([key]))
3069
+ async def ahas_key(self, key: str, *, stampede_prevention: bool | StampedeConfig | None = None) -> bool:
3070
+ config = self.resolve_stampede(stampede_prevention)
3071
+ client = await self.get_async_client()
3072
+ if config is None:
3073
+ return bool(await client.exists([key]))
3074
+ return outlives_buffer(await client.ttl(key), config)
3031
3075
 
3032
3076
  async def atype(self, key: str) -> KeyType | None:
3033
3077
  result: Any = await (await self.get_async_client()).type(key)
@@ -3155,8 +3199,7 @@ class ValkeyGlideAdapter(RespAdapterProtocol):
3155
3199
  if count is None:
3156
3200
  count = self._default_scan_itersize
3157
3201
  result = await client.scan(_enc(cursor), match=match, count=count, type=_object_type(_type))
3158
- keys = [k.decode(errors="surrogateescape") if isinstance(k, bytes) else k for k in result[1]]
3159
- return int(_dec_str(result[0])), keys
3202
+ return int(_dec_str(result[0])), _dec_keys(result[1])
3160
3203
 
3161
3204
  async def aiter_keys(self, pattern: str, itersize: int | None = None):
3162
3205
  async for k in self._ascan_keys(pattern, itersize):
@@ -3233,10 +3276,10 @@ class ValkeyGlideAdapter(RespAdapterProtocol):
3233
3276
 
3234
3277
  async def ahgetall(self, key: str) -> dict[str, Any]:
3235
3278
  result = await (await self.get_async_client()).hgetall(key)
3236
- return {k.decode() if isinstance(k, bytes) else k: v for k, v in result.items()}
3279
+ return {_dec_str(k): v for k, v in result.items()}
3237
3280
 
3238
3281
  async def ahkeys(self, key: str) -> list[str]:
3239
- return [k.decode() if isinstance(k, bytes) else k for k in await (await self.get_async_client()).hkeys(key)]
3282
+ return [_dec_str(k) for k in await (await self.get_async_client()).hkeys(key)]
3240
3283
 
3241
3284
  async def ahvals(self, key: str) -> list[Any]:
3242
3285
  return list(await (await self.get_async_client()).hvals(key))
@@ -3993,6 +4036,8 @@ class ValkeyGlideClusterAdapter(ValkeyGlideAdapter):
3993
4036
  for the other drivers).
3994
4037
  """
3995
4038
 
4039
+ _standalone = False
4040
+
3996
4041
  def _batch_factory(self, *, atomic: bool = False) -> Any:
3997
4042
  return ClusterBatch(is_atomic=atomic)
3998
4043