Summary

Refs #285 and follows the maintainer's proposed subclass hooks rather than adding constructor arguments.

• Expose JSONDisk.json_dumps and JSONDisk.json_loads as static callable attributes and use them consistently for both keys and values.
• Keep default JSON options, UTF-8 encoding, zlib compression, stored bytes, and read=True stream handling unchanged.
• Document subclass/staticmethod customization and the requirement to reuse compatible serialization when reopening a cache.
• Test custom Decimal keys and values with a JSON encoder and loader, inline and file storage, instance overrides, reopen/pickle behavior, default byte compatibility, and binary stream bypass.

The hooks intentionally retain the standard-library string contract: dump returns str, load receives str. Byte-returning serializers can be adapted by decoding in the dump hook; this does not introduce native byte-returning hooks or a new dependency.

Validation

Tested on Windows with Python 3.12.10 and Django 4.2.30, using DJANGO_SETTINGS_MODULE=tests.settings and PYTHONPATH pointing at this checkout:

• Regression before implementation: 3 failed, 7 passed (custom serialization ignored).
• python -m pytest tests/test_jsondisk.py -o addopts='' -q: 10 passed.
• python -m pytest -n 2: 261 passed, 99.13% branch-aware coverage (98% required).
• Blue, isort, Flake8, mypy, Pylint 2.17.7, Sphinx HTML build, doc8, and rstcheck passed.
• doc8/rstcheck used LF-normalized disposable documentation copies for this Windows checkout.
• A separate rollback probe restored the exact pristine source hash; applying the source patch reconstructed the modified hash.

Known tooling output: Django emits its existing USE_L10N deprecation warning, and Blue's Click integration emits duplicate-option warnings. No failures were ignored. Other Python versions were not run locally.

Documentation and scope

The tutorial and API docstring describe the new user-facing hooks. This repository has no current release-note file or README latest-update convention, so no new release-history format was introduced. No dependency or unrelated changes.

AI assistance

AI assisted with implementation, regression tests, local validation, and this PR description. The contributor remains responsible for the submission. No third-party code was copied and no additional runtime dependency was introduced.