Add Disk.with_options(on_error='miss') so unreadable entries are deleted and treated as missing instead of raising

[avgvi]

Adds an opt-in way to treat entries that exist but cannot be read back as missing, which downstream projects have each written by hand: a corrupt pickle, one that refers to a class a library upgrade removed, a value SafeDisk refuses, a stored path outside the cache, or a value file that is not valid text.

• Disk.with_options(on_error='miss') returns a disk type, on any disk class including SafeDisk and the classes with_types returns. Its caches delete such an entry and treat it as missing: get returns its default, cache[key] raises KeyError, pop, pull, peek and peekitem move on, and iteration, Index.items() and Index.values() skip unreadable entries.
• The delete is guarded by the row's mode, filename and value, so an entry rewritten in the meantime is kept; the value file is removed unless the disk refuses the path. The first unreadable entry per cache is logged as a warning on the diskcache_community logger and later ones at debug level.
• A read-only cache does not delete: get returns the default, while peek and peekitem raise because they cannot move past the entry. A missing value file, MemoryError and RecursionError are never treated as unreadable.
• The default stays on_error='raise'. The option is a class attribute and is never persisted, so 5.6.3 still opens the directory.
• Tests in tests/test_entry_errors.py cover each read path, corrupt, stale, refused and tampered entries, statistics and eviction policies, read-only caches, logging, memoize, the containers, Django, a custom disk subclass, and pickling.

Stacked on #24.

Verified: 519 tests pass on Python 3.12, 517 with 2 skipped on 3.10 and 3.14; blue, isort, flake8, mypy, doc8 and the Sphinx build with warnings as errors pass, and pylint reports what it reports on master.

[read-the-docs-community]

Documentation build overview

📚 diskcache-community | 🛠️ Build #35226539 | 📁 Comparing 3148277 against latest (823b63a)

  🔍 Preview build  

7 files changed · ± 7 modified

± Modified

• api.html
• case-study-landing-page-caching.html
• case-study-web-crawler.html
• djangocache-benchmarks.html
• genindex.html
• index.html
• tutorial.html