Skip to content

docs(backends): align backend, CacheManager and CacheLock docs with the code - #359

Merged
allen0099 merged 1 commit into
masterfrom
docs/audit-backends
Sep 29, 2026
Merged

allen0099 merged 1 commit into
masterfrom
docs/audit-backends

Conversation

@allen0099

Copy link
Copy Markdown
Owner

Docs/docstring accuracy audit of the backends, the application cache and the distributed lock. Documentation, docstrings and comments only: no runtime change (verified by an AST comparison against master).

Corrections

  • docs/BACKENDS.md (+ zh-TW), atomic primitives: the page said a counter written with set(key, counter_entry(n)) can be incremented on every backend with Memcached's unsigned range as the only exception. Redis counters are signed 64-bit, so n above 2**63 - 1 also raises CacheXError there. The page now gives both ranges.
  • docs/BACKENDS.md (+ zh-TW), Memcached limitations: clear_pattern returns 0 with a RuntimeWarning (it was only described as unsupported).
  • docs/APP_CACHE.md (+ zh-TW): delete_many() on Redis sends DEL in batches of 100 keys, not one DEL. On Memcached, clear()/clear_prefix()/clear_pattern() return 0 with a RuntimeWarning and are not silent.
  • MemcachedBackend class docstring: the Limitations list covered only clear_pattern. It now also covers get_all_keys/get_cache_data (empty results, with a warning), clear_path (deletes only an exact key) and clear() (flush_all on the whole server).
  • BaseCacheBackend.increment: ValueError is also raised for a delta outside the signed 64-bit range.
  • AsyncRedisCacheBackend.__init__: now documents the CacheXError it raises when redis-py is missing. load_from_config: now documents the RuntimeWarning for a non-UTF-8 encoding and adds the missing blank line before Returns.
  • CacheManager.__init__: TypeError also covers a non-int default_ttl. ValueError also covers values above MAX_TTL and lock_ttl=None.
  • CacheManager.set/add/get_or_set: TypeError for a non-int ttl, and ValueError for values above MAX_TTL.
  • CacheManager.clear_prefix/clear: now say they are no-ops on backends without key enumeration.
  • CacheLock.acquire: now documents BackendNotFoundError when no backend is passed or registered, and says exactly when it returns False.

Possible code issues (not changed here)

  • Counter overflow differs by backend. Redis raises a raw redis.exceptions.ResponseError ("increment or decrement would overflow"), not CacheXError, because backends/redis.py increment converts only the "not an integer" error. Memcached wraps silently past 2**64 - 1 (for example, counter_entry(2**64 - 1) incremented gives 0). The memory backend grows without bound.

@allen0099
allen0099 merged commit 0a3a79c into master Sep 29, 2026
12 checks passed
@allen0099
allen0099 deleted the docs/audit-backends branch September 29, 2026 08:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant