docs(backends): align backend, CacheManager and CacheLock docs with the code - #359
Merged
Merged
Conversation
This was referenced Sep 29, 2026
Open
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 withset(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, sonabove 2**63 - 1 also raisesCacheXErrorthere. The page now gives both ranges.docs/BACKENDS.md(+ zh-TW), Memcached limitations:clear_patternreturns 0 with aRuntimeWarning(it was only described as unsupported).docs/APP_CACHE.md(+ zh-TW):delete_many()on Redis sendsDELin batches of 100 keys, not oneDEL. On Memcached,clear()/clear_prefix()/clear_pattern()return 0 with aRuntimeWarningand are not silent.MemcachedBackendclass docstring: the Limitations list covered onlyclear_pattern. It now also coversget_all_keys/get_cache_data(empty results, with a warning),clear_path(deletes only an exact key) andclear()(flush_allon the whole server).BaseCacheBackend.increment:ValueErroris also raised for adeltaoutside the signed 64-bit range.AsyncRedisCacheBackend.__init__: now documents theCacheXErrorit raises when redis-py is missing.load_from_config: now documents theRuntimeWarningfor a non-UTF-8encodingand adds the missing blank line beforeReturns.CacheManager.__init__:TypeErroralso covers a non-intdefault_ttl.ValueErroralso covers values aboveMAX_TTLandlock_ttl=None.CacheManager.set/add/get_or_set:TypeErrorfor a non-intttl, andValueErrorfor values aboveMAX_TTL.CacheManager.clear_prefix/clear: now say they are no-ops on backends without key enumeration.CacheLock.acquire: now documentsBackendNotFoundErrorwhen no backend is passed or registered, and says exactly when it returnsFalse.Possible code issues (not changed here)
redis.exceptions.ResponseError("increment or decrement would overflow"), notCacheXError, becausebackends/redis.pyincrementconverts 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.