Metadata-Version: 2.5
Name: django-cachex
Version: 0.13.0
Summary: Valkey and Redis cache backends for Django: standalone, Sentinel and Cluster topologies, sync and async APIs, and an ORM query cache
Project-URL: Homepage, https://github.com/oliverhaas/django-cachex
Project-URL: Documentation, https://oliverhaas.github.io/django-cachex/
Project-URL: Repository, https://github.com/oliverhaas/django-cachex.git
Project-URL: Changelog, https://oliverhaas.github.io/django-cachex/latest/reference/changelog/
Author-email: Oliver Haas <ohaas@e1plus.de>
License-Expression: MIT AND BSD-3-Clause
License-File: LICENSE
License-File: LICENSE.django-redis
License-File: django_cachex/orm/LICENSE
Keywords: backend,cache,django,orm,query cache,redis,valkey
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 6.0
Classifier: Framework :: Django :: 6.1
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Free Threading :: 1 - Unstable
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.14
Requires-Dist: django<7,>=6
Requires-Dist: sortedcontainers>=2.4
Provides-Extra: hiredis
Requires-Dist: redis[hiredis]<9,>=7.2; extra == 'hiredis'
Provides-Extra: libvalkey
Requires-Dist: valkey[libvalkey]<7,>=6.1.0; extra == 'libvalkey'
Provides-Extra: lz4
Requires-Dist: lz4>=4.4.0; extra == 'lz4'
Provides-Extra: msgpack
Requires-Dist: msgpack>=1.1.0; extra == 'msgpack'
Provides-Extra: orjson
Requires-Dist: orjson>=3.10.0; extra == 'orjson'
Provides-Extra: ormsgpack
Requires-Dist: ormsgpack>=1.10.0; extra == 'ormsgpack'
Provides-Extra: redis-py
Requires-Dist: redis<9,>=7.2; extra == 'redis-py'
Provides-Extra: valkey-glide
Requires-Dist: valkey-glide-sync<3,>=2.5; extra == 'valkey-glide'
Requires-Dist: valkey-glide<3,>=2.5; extra == 'valkey-glide'
Provides-Extra: valkey-py
Requires-Dist: valkey<7,>=6.1.0; extra == 'valkey-py'
Description-Content-Type: text/markdown

# django-cachex

[![PyPI version](https://img.shields.io/pypi/v/django-cachex.svg?style=flat)](https://pypi.org/project/django-cachex/)
[![Python versions](https://img.shields.io/pypi/pyversions/django-cachex.svg)](https://pypi.org/project/django-cachex/)
[![CI](https://github.com/oliverhaas/django-cachex/actions/workflows/ci.yml/badge.svg)](https://github.com/oliverhaas/django-cachex/actions/workflows/ci.yml)

Valkey and Redis cache backend for Django, with a Django admin UI for cache inspection.
Full documentation at [oliverhaas.github.io/django-cachex](https://oliverhaas.github.io/django-cachex/).

## Quick Start

```console
pip install django-cachex[valkey-py]
```

```python
CACHES = {
    "default": {
        "BACKEND": "django_cachex.cache.ValkeyCache",
        "LOCATION": "valkey://127.0.0.1:6379/1",
    }
}
```

## Features

- One package for Valkey and Redis, standalone, Sentinel and Cluster.
- Sync and async methods on every cache (`get()` and `aget()`), from one alias and one configuration.
- Hash, list, set, sorted set and stream operations, and TTL and pattern helpers (`ttl()`, `expire()`, `keys()`, `delete_pattern()`).
- Distributed locks with `cache.lock()`.
- Counting and weighted semaphores with `cache.semaphore()`, in-process or distributed.
- Lua scripting with `eval_script()`, with optional key-prefixing and encoding hooks.
- Pluggable serializers (Pickle, JSON, MsgPack, ormsgpack, orjson) and compressors (Zlib, Gzip, LZ4, LZMA, Zstandard), each with a fallback chain to migrate between formats.
- Cache stampede prevention (TTL-based XFetch).
- `TrackingCache`, a local read cache over a Redis or Valkey alias, invalidated by the server's `CLIENT TRACKING` or bounded by a local TTL.
- 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.
- `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.
- Experimental `ValkeyGlideCache` and `ValkeyGlideClusterCache` backends on `valkey-glide`, Valkey's official client with a Rust core.

## Cache Admin

Add `django_cachex.admin` to `INSTALLED_APPS` to enable the cache admin:

```python
INSTALLED_APPS = [
    # ...
    "django_cachex.admin",
]
```

The admin lists every configured cache, finds keys by wildcard pattern and type, and edits values and TTLs. It also shows server info and memory statistics, and with `CACHEX_ADMIN = {"ALLOW_FLUSH": True}` it flushes caches.

![Cache list](https://raw.githubusercontent.com/oliverhaas/django-cachex/main/docs/assets/screenshot-cache-list.png)
![Key list](https://raw.githubusercontent.com/oliverhaas/django-cachex/main/docs/assets/screenshot-key-list.png)
![Key detail](https://raw.githubusercontent.com/oliverhaas/django-cachex/main/docs/assets/screenshot-key-detail.png)

## Requirements

- Python 3.14+, including the free-threaded build (3.14t). On 3.14t, importing `hiredis` or `libvalkey` re-enables the GIL with a `RuntimeWarning`, unless you run with `PYTHON_GIL=0` (or `-Xgil=0`).
- Django 6.0 to 6.x (`Django>=6,<7`)
- valkey-py 6.1 to 6.x (`valkey>=6.1,<7`) or redis-py 7.2 to 8.x (`redis>=7.2,<9`)
- Valkey 7.2+ or Redis 6.2+ on the server. [Installation](https://oliverhaas.github.io/django-cachex/latest/getting-started/installation/) lists the methods that need a newer server.
- `valkey-glide` 2.5 to 2.x (the `valkey-glide` extra) for the glide backends. They need the cp314 GIL build and have no Sentinel variant.

## Acknowledgments

This project started from [django-redis](https://github.com/jazzband/django-redis) and Django's official [Redis cache backend](https://docs.djangoproject.com/en/stable/topics/cache/#redis). The admin UI was inspired by [django-redisboard](https://github.com/ionelmc/django-redisboard). The ORM cache is derived from [django-cachalot](https://github.com/noripyt/django-cachalot) 2.9.1 by Bertrand Bordage. The ASGI benchmark follows the shape of [django-vcache](https://gitlab.com/glitchtip/django-vcache)'s `bench_compare.py` (MIT, by David Burke / GlitchTip).

See also [django-valkey](https://github.com/django-commons/django-valkey) and [dj-cache-panel](https://github.com/yassi/dj-cache-panel) for related projects with similar goals.

## License

MIT, see [LICENSE](https://github.com/oliverhaas/django-cachex/blob/main/LICENSE), except for two parts under BSD-3-Clause:

- The ORM cache, `django_cachex/orm/`, derived from django-cachalot. See
  [django_cachex/orm/LICENSE](https://github.com/oliverhaas/django-cachex/blob/main/django_cachex/orm/LICENSE).
- Parts of `django_cachex/serializers/`, `django_cachex/compressors/` and
  `django_cachex/exceptions.py`, derived from django-redis (Copyright (c)
  2011-2016 Andrey Antukh). Each derived file says so in its header. See
  [LICENSE.django-redis](https://github.com/oliverhaas/django-cachex/blob/main/LICENSE.django-redis).
