action0-django-acache 0.1.0__tar.gz

action0_django_acache-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,137 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# cancel superseded runs of the same branch / PR
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    name: checks (python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    continue-on-error: ${{ matrix.experimental }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+        experimental: [false]
+        include:
+          # 3.15 is still a pre-release: run it, but don't fail the whole
+          # workflow while parts of the toolchain don't support it yet
+          - python-version: "3.15"
+            experimental: true
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: ruff format
+        run: uv run ruff format --check
+
+      - name: ruff check
+        run: uv run ruff check
+
+      - name: mypy
+        run: uv run mypy
+
+      - name: pyright
+        run: uv run pyright
+
+      - name: ty
+        run: uv run ty check
+
+      - name: pytest
+        run: uv run pytest
+
+  servers:
+    # the checks above run against fakeredis; this runs the same tests against real servers
+    name: tests against ${{ matrix.server.image }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        server:
+          - { image: "redis:8", cli: redis-cli }
+          - { image: "redis:7", cli: redis-cli }
+          - { image: "valkey/valkey:9", cli: valkey-cli }
+          - { image: "valkey/valkey:8", cli: valkey-cli }
+    services:
+      server:
+        image: ${{ matrix.server.image }}
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "${{ matrix.server.cli }} ping"
+          --health-interval 2s
+          --health-timeout 5s
+          --health-retries 15
+    env:
+      # the tests flush this database; the service container is thrown away afterwards
+      REDIS_URL: redis://localhost:6379/0
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: pytest
+        run: uv run pytest
+
+  docs:
+    name: docs build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+
+      - name: Install dependencies
+        run: uv sync --locked --group docs
+
+      - name: Build documentation (warnings are errors)
+        run: uv run --group docs sphinx-build -W --keep-going -b html docs docs/_build/html
+
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/_build/html
+
+  deploy-docs:
+    name: deploy docs
+    # publish only what landed on main
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: docs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    # the Pages site itself was enabled once via
+    # `gh api repos/<owner>/<repo>/pages -X POST -f build_type=workflow`;
+    # creating it from a workflow is impossible (GITHUB_TOKEN cannot get
+    # repo-administration rights)
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

action0_django_acache-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,62 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    name: check and build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Run all checks
+        run: |
+          uv run ruff format --check
+          uv run ruff check
+          uv run mypy
+          uv run pyright
+          uv run ty check
+          uv run pytest
+
+      - name: Check that the tag matches __version__
+        run: |
+          version=$(uv run python -c "from action0.django_acache import __version__; print(__version__)")
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "tag $GITHUB_REF_NAME does not match __version__ $version" >&2
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/action0-django-acache
+    permissions:
+      # OIDC token for PyPI trusted publishing
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

action0_django_acache-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Editor files
+.idea
+
+# Claude Code local state
+.claude/settings.local.json
+.claude/worktrees/
+
+# Sphinx build output
+docs/_build/

action0_django_acache-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

action0_django_acache-0.1.0/CLAUDE.md

@@ -0,0 +1,76 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+`action0-django-acache` is a Django cache backend: Django's own Redis backend (`django.core.cache.backends.redis.RedisCache`) subclassed so that its async methods (`aget`, `aset`, ...) run natively on `redis.asyncio` instead of wrapping the sync methods in `sync_to_async`. It ships the `action0.django_acache` package (`action0` is a PEP 420 namespace package) from a `src/` layout, is built with hatchling, and uses `uv` for environment/dependency management. Runtime dependencies: `django>=5.2` and `redis>=5.0.1`; the `hiredis` extra passes through to `redis[hiredis]`. Settings use it as `"BACKEND": "action0.django_acache.RedisCache"`.
+
+## Rules
+
+- **Never commit without asking.** Also never push, tag, or publish on your own.
+- **Branches + PRs.** All changes go through feature branches and GitHub pull requests that Simon reviews and merges — never commit to `main` directly. (Only the initial implementation is built directly on `main`; once that phase is over, this applies without exception.)
+- **Discuss first.** Always present the plan and the intended edits and get agreement before changing files.
+- Every code change comes with: tests, docstrings, inline comments where the code isn't self-explanatory, and updated usage examples in `README.md` and the Sphinx docs (`docs/usage.md`).
+- Before considering work done, run ruff, mypy, pyright, ty and pytest (commands below) and fix what they report.
+- Supported Python versions: 3.11 up to the latest release. Don't use syntax or stdlib features introduced after 3.11 (no PEP 695 `type` aliases or generics — use `TypeAlias`), and don't rely on behavior removed in newer versions.
+- Prefer many small modules and short functions over large ones.
+
+## Commands
+
+`uv run` syncs the environment automatically (the dev dependency group is installed by default), so no separate install step is needed.
+
+```sh
+uv run pytest                                              # all tests (fakeredis)
+uv run pytest tests/action0/django_acache/test_pools.py   # one file
+uv run pytest tests/action0/django_acache/test_pools.py::LifecycleTestCase::test_threads  # one test
+REDIS_URL=redis://localhost:6379/15 uv run pytest          # against a real server (flushes that db!)
+
+uv run --with "django==5.2.*" pytest   # the oldest supported Django (the lock has 6.x on 3.12+)
+uv run --with "redis==5.0.1" pytest    # the oldest supported redis-py
+
+uv run ruff check      # lint (add --fix to autofix)
+uv run ruff format     # format
+uv run mypy            # type-check (strict; files are configured in pyproject.toml)
+uv run pyright         # type-check
+uv run ty check        # type-check
+
+uv run --group docs sphinx-build -W --keep-going -b html docs docs/_build/html  # build docs
+
+uv build               # build sdist + wheel into dist/
+```
+
+`pytest` also runs the `>>>` examples in the docstrings as doctests (`--doctest-modules` over `src/`), so docstring examples must produce their shown output exactly. pytest turns **every warning into an error** (`filterwarnings = ["error"]`) — deliberately, because the `ResourceWarning`s redis-py emits for unclosed connections are exactly what the pool lifecycle must prevent.
+
+## Architecture
+
+Modules under `src/action0/django_acache/`, from the leaves up (`options.py` uses `validation.py`):
+
+- `options.py` — `async_pool_config(pool_options, overrides)`: derives the async pool class and pool kwargs from the kwargs Django built for its sync pools (`RedisCacheClient._pool_options`) plus the cache's `ASYNC_OPTIONS`. `pool_class`/`parser_class` default to the `redis.asyncio` variants (never the sync ones from `OPTIONS`) and accept dotted paths; `serializer` may not be overridden (both sides must read each other's values).
+- `validation.py` — `check_async_options(options, overrides)`, called by `async_pool_config`: rejects sync redis-py values that would reach the async pools (`RULES`: `pool_class` must subclass `redis.asyncio.ConnectionPool`, `connection_class` `redis.asyncio.connection.AbstractConnection`, `retry` must be a `redis.asyncio.retry.Retry` or `None`) with an `ImproperlyConfigured` naming the key, whether it came from `OPTIONS` or `ASYNC_OPTIONS`, and the fix. Simon's decision; the motivating case: a sync `Retry` on an async connection is accepted silently and never retries (measured: 1 connect attempt instead of 4). Runs when the client is built, i.e. on the cache's first use — sync use included.
+- `pools.py` — `PoolRegistry` and the module-level `registry`: one shared `redis.asyncio.Redis` client (and its pool) per running event loop and per configuration (pool class, URL, options). Lookup compares options by identity, then equality — not by hash, because Django passes an unhashable `redis.DriverInfo` dataclass. On a loop's first use the registry starts an async generator on it (`_close_at_shutdown`) whose `finally` closes that loop's pools; `loop.shutdown_asyncgens()` (called by `asyncio.run`, `asyncio.Runner`, uvicorn, asgiref's `async_to_sync`, `IsolatedAsyncioTestCase`) triggers it. `aclose()`/`aclose_pools()` close the running loop's pools early by closing that generator, i.e. through the same path. Loops closed without shutting down their async generators are purged when the next new loop registers.
+- `client.py` — `RedisCacheClient(django RedisCacheClient)`: an async twin (`aadd`, `aget`, ...) of every sync method, line by line, plus `aget_client()` which asks the registry. Takes `async_options` in addition to Django's client arguments.
+- `backend.py` — `RedisCache(django RedisCache)`: reads `ASYNC_OPTIONS` from the cache params, builds the client with it (`_cache`), and overrides every async method Django would otherwise hand to a thread: `aadd aget aset atouch adelete aget_many ahas_key aincr aset_many adelete_many aclear aclose`. The rest (`adecr`, `aget_or_set`, `aincr_version`, `adecr_version`) are Django's generic `BaseCache` versions, which build on these natively — `test_async_methods_never_use_the_sync_client` guards that. `get_backend_timeout` is overridden only to type the result as `int | None`.
+
+Deliberate decisions worth keeping, all confirmed by Simon — don't reopen them without a new reason:
+
+- **Pools shared per event loop, not per cache instance.** Under ASGI Django creates a cache instance per request (the cache handler stores instances in an asgiref context-local; a task only sees instances its parent context already created). Per-instance pools would open a connection per request and leak them. Rejected alternative: per-instance pools closed by an async `request_finished` receiver — a TCP connect per request, and code outside requests (management commands, `async_to_sync`, Celery) would still need the loop-shutdown hook.
+- **One class for sync + async**, extending Django's backend; the sync side stays Django's untouched code.
+- **`ASYNC_OPTIONS`** as a top-level cache setting next to `OPTIONS`, overriding keys for the async side. Rejected alternatives: nested `OPTIONS["async"]` and `async_*` prefixed keys — both would make the settings invalid for Django's stock backend, whereas a top-level key keeps them switchable.
+- **One shared `redis.asyncio.Redis` per pool** instead of one per call like Django's sync side: constructing one costs ~47µs, about a local round trip.
+- `aclose()` (and Django's per-request `close()`) do not close the shared pools.
+- Tests: fakeredis locally (sync and async pools sharing one `FakeServer`), plus a CI job running the same suite against real Redis and Valkey containers via `REDIS_URL`.
+
+Conventions:
+
+- The version is single-sourced as `__version__` in `src/action0/django_acache/__init__.py`; hatch extracts it with the regex in `[tool.hatch.version]`. Bump it only there.
+- Releases: pushing a `vX.Y.Z` tag triggers `.github/workflows/release.yml`, which re-runs all checks, verifies the tag matches `__version__`, builds, and publishes to PyPI via trusted publishing (environment `pypi`). Never bump the version, tag, or publish on your own — releasing is the user's call.
+- CI (`ci.yml`): the checks matrix (Python 3.11–3.14, experimental 3.15) against fakeredis; the `servers` job runs pytest against `redis:8`, `redis:7`, `valkey/valkey:9`, `valkey/valkey:8` service containers; docs build + Pages deploy.
+- The dev group pins `django>=6.0; python_version >= '3.12'` so the lock forks: Django 5.2 on 3.11, the latest Django on 3.12+. CI's 3.11 job is therefore the Django 5.2 test.
+- Django and redis-py private attributes the code relies on (`_servers`, `_serializer`, `_pool_options`, `_pools`, `_get_connection_pool_index`, `_options`) are declared as annotations in the subclasses, because django-stubs doesn't list them. The async `DefaultParser` class depends on the redis-py version and on hiredis — never assert its concrete name.
+- Tests mirror the `src/` layout under `tests/action0/django_acache/` (a regular package, for the relative imports of `support.py`) and are `unittest.TestCase`/`IsolatedAsyncioTestCase` classes, executed via pytest. `support.py` configures Django settings and provides `cache_settings()`, `make_cache()`, `async_server()` and `CacheTestCase`. Tests that use the sync side must close its pools (`close_sync_pools`), or a real server's sockets raise `ResourceWarning`. Cache keys in tests must be memcached-safe (no spaces), or Django's `CacheKeyWarning` fails them. Real-server tests: the Django cache handler shares instances with child tasks once the parent context touched them — simulate separate requests without touching `caches` in the parent.
+- When an ignore is unavoidable, silence each checker with its own syntax (`# type: ignore[code]  # ty: ignore[code]`). ty picks redis-py 8's sync overload for some async commands (e.g. `incr`), hence one `ty: ignore[invalid-await]`.
+- Ruff enforces one import per line (isort `force-single-line`), line length 99, `action0` as first-party. Ruff only honours `.gitignore` inside a git repository.
+- Docs live in `docs/` (Sphinx + Furo, MyST Markdown pages, autodoc for the API reference, intersphinx to Python, Django and redis-py). Docstrings are Sphinx-reST (`:param:`, `:py:func:` roles). CI builds them with `-W` on every run and deploys to GitHub Pages on pushes to `main`. Examples in `docs/usage.md` and `README.md` must stay truthful.
+- The GitHub Pages site must be enabled once per repo before `deploy-docs` can run: `gh api repos/LaughInJar/action0-django-acache/pages -X POST -f build_type=workflow`.
+- The README carries an AI-usage disclosure section — keep it accurate when the development workflow changes.

action0_django_acache-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LaughInJar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

action0_django_acache-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.5
+Name: action0-django-acache
+Version: 0.1.0
+Summary: Django's Redis cache backend with native async methods on redis.asyncio
+Project-URL: Homepage, https://github.com/LaughInJar/action0-django-acache
+Project-URL: Documentation, https://laughinjar.github.io/action0-django-acache/
+Project-URL: Source, https://github.com/LaughInJar/action0-django-acache
+Project-URL: Issues, https://github.com/LaughInJar/action0-django-acache/issues
+Author: Simon Lachinger
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asgi,async,asyncio,cache,django,redis,valkey
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Database
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: django>=5.2
+Requires-Dist: redis>=5.0.1
+Provides-Extra: hiredis
+Requires-Dist: redis[hiredis]>=5.0.1; extra == 'hiredis'
+Description-Content-Type: text/markdown
+
+# Action0-Django-ACache
+
+[![CI](https://github.com/LaughInJar/action0-django-acache/actions/workflows/ci.yml/badge.svg)](https://github.com/LaughInJar/action0-django-acache/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/action0-django-acache)](https://pypi.org/project/action0-django-acache/)
+
+Django's Redis cache backend with async methods that are actually async: they
+talk to the server through `redis.asyncio` instead of running the sync methods
+in a worker thread.
+
+Requires Python 3.11 or newer, Django 5.2 or newer and redis-py 5.0.1 or newer.
+Works with Redis and Valkey.
+
+Full documentation including the API reference:
+<https://laughinjar.github.io/action0-django-acache/>
+
+**Status:** early. Every async cache method is native and covered by tests
+(against fakeredis, and in CI against Redis 7/8 and Valkey 8/9); the API may
+still move.
+
+## Installation
+
+```shell
+pip install action0-django-acache            # or: uv add action0-django-acache
+pip install "action0-django-acache[hiredis]"  # with the C parser
+```
+
+## Usage
+
+Swap the backend in your settings — everything else stays as with Django's
+Redis backend:
+
+```python
+CACHES = {
+    "default": {
+        "BACKEND": "action0.django_acache.RedisCache",
+        "LOCATION": "redis://127.0.0.1:6379",
+    },
+}
+```
+
+And await the cache in async code as usual:
+
+```python
+from django.core.cache import cache
+
+
+async def weather(request, city):
+    report = await cache.aget(f"weather:{city}")
+    if report is None:
+        report = await fetch_weather(city)
+        await cache.aset(f"weather:{city}", report, timeout=300)
+    ...
+```
+
+Django's own `RedisCache` runs every one of these calls in a thread via
+`sync_to_async` (and on Django 5.2 its `aincr` is not even atomic: a get, then
+a set). Here `aget`, `aset`, `aadd`, `atouch`, `adelete`, `ahas_key`,
+`aget_many`, `aset_many`, `adelete_many`, `aincr` and `aclear` are coroutines
+on `redis.asyncio`, and `aincr` is a single `INCRBY` on the server.
+
+The sync methods are Django's, untouched, and both sides write the same keys
+with the same serializer: sync and async code share one cache.
+
+A few redis-py options come in a sync and an async variant. `ASYNC_OPTIONS`
+overrides `OPTIONS` for the async side only — and a sync class or `Retry` that
+would still reach the async side is an `ImproperlyConfigured` error naming the
+fix:
+
+```python
+CACHES = {
+    "default": {
+        "BACKEND": "action0.django_acache.RedisCache",
+        "LOCATION": "redis://127.0.0.1:6379",
+        "OPTIONS": {
+            "pool_class": "redis.BlockingConnectionPool",
+            "max_connections": 50,
+        },
+        "ASYNC_OPTIONS": {
+            "pool_class": "redis.asyncio.BlockingConnectionPool",
+        },
+    },
+}
+```
+
+Under ASGI, Django creates a cache instance per request. The async connection
+pools are therefore shared per event loop — all requests reuse the same
+connections — and closed when the loop shuts down. `aclose_pools()` closes
+them earlier:
+
+```python
+from action0.django_acache import aclose_pools
+
+await aclose_pools()
+```
+
+See the [usage guide](https://laughinjar.github.io/action0-django-acache/usage.html)
+for the details: which method sends which commands, every `ASYNC_OPTIONS` key,
+the pool lifecycle, and a fakeredis setup for your tests.
+
+The `action0` namespace is simply the one the author likes to use for
+personal projects.
+
+## Development
+
+```shell
+uv run pytest          # tests (incl. doctests in src/), against fakeredis
+uv run ruff check      # lint
+uv run ruff format     # format
+uv run mypy            # type-check (strict)
+uv run pyright         # type-check
+uv run ty check        # type-check
+```
+
+`REDIS_URL=redis://localhost:6379/15 uv run pytest` runs the tests against a
+real server instead — they flush that database.
+
+## AI disclosure
+
+This library is developed with heavy use of AI coding tools: the code,
+tests, and documentation are largely written by
+[Claude Code](https://claude.com/claude-code), working from the author's
+design brief and reviewed by the author. If that changes how much you want
+to rely on this package, that's a fair call — read the source, it's small.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

action0_django_acache-0.1.0/README.md

@@ -0,0 +1,127 @@
+# Action0-Django-ACache
+
+[![CI](https://github.com/LaughInJar/action0-django-acache/actions/workflows/ci.yml/badge.svg)](https://github.com/LaughInJar/action0-django-acache/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/action0-django-acache)](https://pypi.org/project/action0-django-acache/)
+
+Django's Redis cache backend with async methods that are actually async: they
+talk to the server through `redis.asyncio` instead of running the sync methods
+in a worker thread.
+
+Requires Python 3.11 or newer, Django 5.2 or newer and redis-py 5.0.1 or newer.
+Works with Redis and Valkey.
+
+Full documentation including the API reference:
+<https://laughinjar.github.io/action0-django-acache/>
+
+**Status:** early. Every async cache method is native and covered by tests
+(against fakeredis, and in CI against Redis 7/8 and Valkey 8/9); the API may
+still move.
+
+## Installation
+
+```shell
+pip install action0-django-acache            # or: uv add action0-django-acache
+pip install "action0-django-acache[hiredis]"  # with the C parser
+```
+
+## Usage
+
+Swap the backend in your settings — everything else stays as with Django's
+Redis backend:
+
+```python
+CACHES = {
+    "default": {
+        "BACKEND": "action0.django_acache.RedisCache",
+        "LOCATION": "redis://127.0.0.1:6379",
+    },
+}
+```
+
+And await the cache in async code as usual:
+
+```python
+from django.core.cache import cache
+
+
+async def weather(request, city):
+    report = await cache.aget(f"weather:{city}")
+    if report is None:
+        report = await fetch_weather(city)
+        await cache.aset(f"weather:{city}", report, timeout=300)
+    ...
+```
+
+Django's own `RedisCache` runs every one of these calls in a thread via
+`sync_to_async` (and on Django 5.2 its `aincr` is not even atomic: a get, then
+a set). Here `aget`, `aset`, `aadd`, `atouch`, `adelete`, `ahas_key`,
+`aget_many`, `aset_many`, `adelete_many`, `aincr` and `aclear` are coroutines
+on `redis.asyncio`, and `aincr` is a single `INCRBY` on the server.
+
+The sync methods are Django's, untouched, and both sides write the same keys
+with the same serializer: sync and async code share one cache.
+
+A few redis-py options come in a sync and an async variant. `ASYNC_OPTIONS`
+overrides `OPTIONS` for the async side only — and a sync class or `Retry` that
+would still reach the async side is an `ImproperlyConfigured` error naming the
+fix:
+
+```python
+CACHES = {
+    "default": {
+        "BACKEND": "action0.django_acache.RedisCache",
+        "LOCATION": "redis://127.0.0.1:6379",
+        "OPTIONS": {
+            "pool_class": "redis.BlockingConnectionPool",
+            "max_connections": 50,
+        },
+        "ASYNC_OPTIONS": {
+            "pool_class": "redis.asyncio.BlockingConnectionPool",
+        },
+    },
+}
+```
+
+Under ASGI, Django creates a cache instance per request. The async connection
+pools are therefore shared per event loop — all requests reuse the same
+connections — and closed when the loop shuts down. `aclose_pools()` closes
+them earlier:
+
+```python
+from action0.django_acache import aclose_pools
+
+await aclose_pools()
+```
+
+See the [usage guide](https://laughinjar.github.io/action0-django-acache/usage.html)
+for the details: which method sends which commands, every `ASYNC_OPTIONS` key,
+the pool lifecycle, and a fakeredis setup for your tests.
+
+The `action0` namespace is simply the one the author likes to use for
+personal projects.
+
+## Development
+
+```shell
+uv run pytest          # tests (incl. doctests in src/), against fakeredis
+uv run ruff check      # lint
+uv run ruff format     # format
+uv run mypy            # type-check (strict)
+uv run pyright         # type-check
+uv run ty check        # type-check
+```
+
+`REDIS_URL=redis://localhost:6379/15 uv run pytest` runs the tests against a
+real server instead — they flush that database.
+
+## AI disclosure
+
+This library is developed with heavy use of AI coding tools: the code,
+tests, and documentation are largely written by
+[Claude Code](https://claude.com/claude-code), working from the author's
+design brief and reviewed by the author. If that changes how much you want
+to rely on this package, that's a fair call — read the source, it's small.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

action0_django_acache-0.1.0/docs/api.md

@@ -0,0 +1,46 @@
+# API reference
+
+Everything public is importable from the package root:
+
+```python
+from action0.django_acache import (
+    PoolRegistry,
+    RedisCache,
+    RedisCacheClient,
+    aclose_pools,
+    registry,
+)
+```
+
+## Backend
+
+```{eval-rst}
+.. automodule:: action0.django_acache.backend
+   :members:
+```
+
+## Client
+
+```{eval-rst}
+.. automodule:: action0.django_acache.client
+   :members: RedisCacheClient
+```
+
+## Pools
+
+```{eval-rst}
+.. automodule:: action0.django_acache.pools
+   :members: aclose_pools, registry, PoolRegistry
+```
+
+## Options
+
+```{eval-rst}
+.. automodule:: action0.django_acache.options
+   :members:
+```
+
+```{eval-rst}
+.. automodule:: action0.django_acache.validation
+   :members: check_async_options, RULES
+```