Metadata-Version: 2.5
Name: django-cachex
Version: 0.4.0
Summary: Full featured Valkey and Redis cache backend for Django
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/reference/changelog/
Author-email: Oliver Haas <ohaas@e1plus.de>
License-Expression: MIT
License-File: LICENSE
Keywords: backend,cache,django,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,>=6; 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,>=6; extra == 'redis-py'
Provides-Extra: redis-rs
Requires-Dist: django-cachex-redis-rs==0.4.0; extra == 'redis-rs'
Provides-Extra: valkey-glide
Requires-Dist: valkey-glide-sync<3,>=2.3; extra == 'valkey-glide'
Requires-Dist: valkey-glide<3,>=2.3; 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.

## Installation

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

## Quick Start

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

## What's in the box

- One package for both Valkey and Redis, default and Sentinel and Cluster.
- Sync and async are first-class. The async cache also works from sync code.
- Hash, list, set, sorted set, and stream operations on the cache object.
- TTL and pattern helpers (`ttl()`, `expire()`, `keys()`, `delete_pattern()`).
- Distributed locks: `cache.lock()`.
- Weighted semaphores: `cache.semaphore()` for budget-based concurrency gating (counting and weighted, in-process and distributed).
- Lua scripting with automatic key prefixing and value encoding/decoding.
- Pluggable serializers (Pickle, JSON, MsgPack, ormsgpack, orjson) and compressors (Zlib, Gzip, LZ4, LZMA, Zstandard), each with fallback chains for safe migrations.
- Cache stampede prevention (TTL-based XFetch).
- Two composite backends: `StreamCache` (cross-pod stream-synchronized in-memory cache) and `TieredCache` (L1/L2 with TTL propagation).
- Django `LocMemCache` and `DatabaseCache` extensions with the same data-structure ops and admin support.
- Optional Rust I/O driver (PyO3 + tokio + redis-rs) under the same `RespCache` API. Free-threaded CPython (3.14t) supported. Experimental.
- Optional `valkey-glide` adapter: Valkey's official Rust-cored client, exposed as `ValkeyGlideCache`. Experimental.
- Django admin UI for browsing keys, inspecting values, editing, and flushing. See below.

## Cache Admin

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

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

Browse all configured caches, search and filter keys by type, and manage values directly:

![Cache list](docs/assets/screenshot-cache-list.png)
![Key list](docs/assets/screenshot-key-list.png)
![Key detail](docs/assets/screenshot-key-detail.png)

Features:
- Browse all configured cache backends (Valkey, Redis, LocMemCache, DatabaseCache, and more)
- Search keys with wildcard patterns (`user:*`, `*:session`)
- Filter by key type (string, list, set, hash, zset, stream)
- View and edit values with type-specific operations
- Inspect and modify TTL
- View server info and memory statistics
- Flush caches

## Documentation

Full documentation at [oliverhaas.github.io/django-cachex](https://oliverhaas.github.io/django-cachex/)

## Requirements

- Python 3.14+ (free-threaded supported)
- Django 6.0+
- valkey-py 6.1+ or redis-py 6.0+
- Valkey 7.0+ or Redis 6.0+ on the server (the admin's compare-and-swap
  edits use `SET ... KEEPTTL`, which lands in Redis 6.0)

The Rust I/O driver is optional and experimental: interfaces and
behavior may still change, and it has seen less production testing than
the redis-py/valkey-py paths. To opt in, install with the `redis-rs`
extra (`pip install django-cachex[redis-rs]`); this pulls in the
`django-cachex-redis-rs` companion package. Prebuilt wheels are published
for Linux x86_64, Linux aarch64, macOS arm64, and Windows amd64, on
both cp314 and cp314t (free-threaded). Without the extra, the
`RedisRsCache` backends are unavailable but everything else works.

The `valkey-glide` adapter is also optional and experimental, with the
same caveats. Install with the `valkey-glide` extra
(`pip install django-cachex[valkey-glide]`) to enable
`ValkeyGlideCache`; it pulls in `valkey-glide-sync` and `valkey-glide`,
the official Rust-cored Valkey client. cp314 GIL only; no free-threaded
wheels yet. Cluster is supported via `ValkeyGlideClusterCache`; Sentinel
is not currently exposed (`valkey-glide` itself does not ship a Sentinel
client).

## 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). Some serializer and compressor utility code is derived from django-redis, licensed under BSD-3-Clause. The admin UI was inspired by [django-redisboard](https://github.com/ionelmc/django-redisboard).

The Rust I/O driver and async bridge are heavily inspired by, and in places directly adapted from, [django-vcache](https://gitlab.com/glitchtip/django-vcache) (MIT, by David Burke / GlitchTip). The fork-safe tokio runtime, the `RedisRsAwaitable` deferred-loop-binding pattern, and the multiplexed-connection design all originate there.

I also want to mention [django-valkey](https://github.com/django-commons/django-valkey) and [dj-cache-panel](https://github.com/yassi/dj-cache-panel), which I never really used, but are newer and interesting efforts of similar goals as this package has.

## License

MIT
