Allow customizing JSONDisk serialization with subclass hooks

[Gonghan-Princess]

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.

[carlitogwapito]

Small negative-test companion to the working-hook cases: test-only commit. It's one new file with no implementation changes.

Four cases reject a key or replacement value, with inline and file-backed storage. They check that the hook's ValueError leaves the original entry and .val files intact, then close and reopen the cache to check the saved data again.

I ran the unchanged test bodies against the complete pinned core modules on Windows/Python 3.14.4, SQLite 3.50.4. All four pass with this branch. On the base, all four rejection checks fail because the new hook attributes are ignored. That's a feature-boundary check, not a claim that ordinary baseline writes are corrupt.

Two useful guards here: rejection before persistence, and cold readback in both storage modes. Focused Ruff checks pass; I haven't run the full Django/package suite, tox, coverage matrix, or Blue/Flake8/isort toolchain. Take whichever cases help.

[Gonghan-Princess]

Adopted your four cases in 98adfc0, preserving your author credit, with a Blue-only formatting follow-up in da3437f. These add rejection/persistence coverage absent from the existing hook tests; no implementation changes were needed.

Local macOS/Python 3.9.6 validation: 14 focused tests passed; the full Django/package and doctest suite passed all 265 tests with 99.03% coverage. Blue, Flake8 and isort pass for the new file. Against the upstream base, the same four cases fail at the expected ValueError checks because the base ignores the hooks; this verifies the feature boundary, without suggesting ordinary baseline writes corrupt data. GitHub workflow 39191234466 is currently completed/action_required before any jobs ran, so the new head has no passing GitHub CI result yet.