â ī¸ Deprecations & removals:
đž Serialization:
serializer='json' will no longer automatically use ultrajson if installed; it must be specified explicitlybson codec; please install pymongo to use BSON serialization[bson] package extra to prevent accidentally installing it in the same environment as pymongo.bson file extension by defaultorjson as a JSON serializerjson_serializer, ujson_serializer, and orjson_serializer[json] package extra due to multiple supported JSON librariesdecode_content to be set to different values across multiple sessions in use at the same timeđž Backends:
requests_cache.backends.filesystem.LRUFileDict class to optionally limit the size of the filesystem cache. Enabled with max_cache_bytes argument.SCAN and HSCAN instead of KEYS, HKEYS, and HGETALLcreate_table of DynamoDBCache to control if the class attempts to create the table in DynamoDB or not.connection parameter to allow passing an existing MongoClient objectđ Expiration & headers:
Vary: Cookieâī¸ Session settings:
autoclose option to close backend connections when the session is closedread_only option to read existing cached responses, but not write any new responses to the cacheâšī¸ Cache convenience methods:
verify parameter to BaseCache.contains() and delete() to handle requests made with SSL verification disabled𧊠Compatibility and packaging:
đĒ˛ Bugfixes:
content_root_key setting to target a sub-tree in normalize_json_body, so only listed fields under that key are ignored in cache keyssqlite3.InterfaceError: bad parameter or other API misuse with concurrent SQLite usage in python 3.12+requests-cache <= 1.1stale_if_error during revalidation requestsinstall_cache()expire_after is set to DO_NOT_CACHEcache_name and a backend instance (database names, file paths, etc. cannot be reliably updated after initialization)Content-Length and Transfer-EncodingđĒ˛ Bugfixes:
normalize_headers not accepting header values in bytesCachedResponse.expires_unix propertydecode_content=True when the root element is an empty list or objectresponses library to be compatible with requests 2.32â ī¸ Deprecations & removals:
CachedSession and BaseCacheđ Expiration & headers:
X-HTTP-Method-Override and other headers that can override request methodâī¸ Session methods:
CachedSession.wrap() classmethod to add caching to an existing requests.Session objectđž SQLite Backend:
vacuum parameter to SQLiteCache.delete() to optionally skip vacuuming after deletion (enabled by default to free up disk space)SQLiteCache.delete() when deleting a single key𧊠Compatibility:
decode_content=True (root element with any type)đĒ˛ Bugfixes:
IncompleteRead error that could sometimes occur with streaming requests due to mismatch with Content-Length headerCachedHTTPResponse._request_url property for compatibility with urllib3verify param, cache the response under the same key as verify=Trueapplication/vnd.api+json) during request normalization and serializationâī¸ Session settings:
urls_expire_afterđž SQLite Backend:
busy_timeout argument (see SQLite docs for details)wal=True), default to ‘normal’ synchronous mode instead of ‘full’OperationalError: database is locked in multithreaded SQLite usage during bulk delete operationsđĒ˛ Bugfixes:
decode_content=True when the root element is a listBaseCache.recreate_keys() to normalize response bodies with b'None'BaseCache.contains() for multipart POST requestsCachedResponse.history not being fully deserialized on python<=3.8Vary and redirectsCachedResponse.url so it always matches the original request URLCache-Control: must-revalidate and no-cache response headers with cache_control=FalseSee all unreleased issues and PRs
đ Expiration & headers:
Cache-Control: min-freshCache-Control: max-staleCache-Control: only-if-cachedCache-Control: stale-if-errorCache-Control: stale-while-errorVaryCache-Control: no-cache request or response headerCache-Control: max-age=0, must-revalidate response headersCachedResponse.revalidated to indicate if a cached response was revalidated for the current requestâī¸ Session settings:
CachedSession.settingsalways_revalidate session setting to always revalidate before using a cached response (if a validator is available).only_if_cached session setting to return only cached results without sending real requestsstale_while_revalidate session setting to return a stale response initially, while a non-blocking request is sent to refresh the responsestale_if_error partially consistent with Cache-Control: stale-if-error: Add support for time values (int, timedelta, etc.) in addition to True/Falseâī¸ Request settings:
only_if_cached option to CachedSession.request() and send() to return only cached results without sending real requestsrefresh option to CachedSession.request() and send() to revalidate with the server before using a cached responseforce_refresh option to CachedSession.request() and send() to awlays make and cache a new request regardless of existing cache contentsexpire_after=0 consistent with Cache-Control: max-age=0: if the response has a validator, save it to the cache but revalidate on use.requests_cache.DO_NOT_CACHE may be used to completely disable caching for a requestđž Backends:
len()) now uses a fast table estimate instead of a full scandecode_content=False.decode_content=False.decode_content=False.ttl_offset argument to add a delay between cache expiration and deletiondelete()count() method to count responses, with option to exclude expired responses (performs a fast indexed count instead of slower in-memory filtering)size() method to get estimated size of the database (including in-memory databases)sorted() method with sorting and other query optionswal parameter to enable write-ahead loggingCachedSession is used as a contextmanager, or if CachedSession.close() is calledâī¸ Request matching:
allowable_methods (previously only skipped write)ignored_parameters, to avoid accidentally storing common credentials in the cache. This will have no effect if ignored_parameters is already set.ignored_parameters (e.g., for a request sent both with and without authentication)a=1 vs ?a=1&a=2)âšī¸ Convenience methods:
expired and invalid arguments to BaseCache.delete() (to replace remove_expired_responses())urls and requests arguments to BaseCache.delete() (to replace delete_url())older_than argument to BaseCache.delete() to delete responses older than a given valuerequests argument to BaseCache.delete() to delete responses matching the given requestsBaseCache.contains() method to check for cached requests either by key or by requests.Request objecturl argument to BaseCache.contains() method (to replace has_url())BaseCache.filter() method to get responses from the cache with various filtersBaseCache.reset_expiration() method to reset expiration for existing responsesBaseCache.recreate_keys() method to recreate cache keys for all previously cached responses (e.g., to preserve cache data after an update that changes request matching behavior)BaseCache.urls into a method that takes optional filter params, and returns sorted unique URLsâšī¸ Response attributes and type hints:
OriginalResponse type, which adds type hints to requests.Response objects for extra attributes added by requests-cache:cache_keycreated_atexpiresfrom_cacheis_expiredrevalidatedOriginalResponse.cache_key and expires will be populated for any new response that was written to the cacheCachedSession.get(), head(), etc.)CachedResponse.cache_key attribute for responses read from lower-level storage methods (items(), values(), etc.)𧊠Compatibility fixes:
AttributeError due to undetected imports when requests-cache is bundled in a PyInstaller packageRedisCache for redis-py 4.2 and python <=3.8MongoCache for pymongo 4.1 and python <=3.8đĒ˛ Bugfixes:
install_cache()OperationalError: database is locked in SQLite backendCachedResponse.created_at timestampCachedRequest.path_url property for compatibility with RequestEncodingMixinAttributeError due to undetected imports when requests-cache is bundled in a PyInstaller packageAttributeError when attempting to unpickle a CachedSession object, and instead disable pickling by raising a NotImplementedErrorstale_if_error if an error response code is added to allowable_codesđĻ Dependencies:
appdirs with platformdirsâ ī¸ Deprecations:
The following methods are deprecated, and will be removed in 1.2. The recommended replacements are listed below. If this causes problems for you, please open an issue to discuss.
CachedSession.remove_expired_responses(): BaseCache.delete(expired=True)BaseCache.remove_expired_responses(): BaseCache.delete(expired=True)BaseCache.delete_url(): BaseCache.delete(urls=[...])BaseCache.delete_urls(): BaseCache.delete(urls=[...])BaseCache.has_key(): BaseCache.contains()BaseCache.has_url(): BaseCache.contains(url=...)BaseCache.keys(): BaseCache.responses.keys() (for all keys), or BaseCache.filter() (for filtering options)BaseCache.values(): BaseCache.responses.values() (for all values), or BaseCache.filter() (for filtering options)BaseCache.response_count(): len(BaseCache.responses) (for all responses), or BaseCache.filter() (for filtering options)â ī¸ Breaking changes:
CachedSession.settings. Previously, some settings could be modified by setting them on either CachedSession or BaseCache. In some cases this could silently fail or otherwise have undefined behavior.BaseCache.urls has been replaced with a method that returns a list of URLs.Minor breaking changes:
The following changes only affect advanced or undocumented usage, and are not expected to impact most users:
match_headers and ignored_parameters must be passed to CachedSession. Previously, these could also be passed to a BaseCache instance.CachedSession backend argument must be either an instance or string alias. Previously it would also accept a backend class.BaseStorage subclasses have been removed, and merged into their respective parent classes. This includes SQLitePickleDict, MongoPickleDict, and GridFSPickleDict.BaseStorage subclasses now have a serializer attribute, which will be unused if set to None.cache_control module (added in 0.7) has been split up into multiple modules in a new policy subpackageDeprecationWarning raised by BaseCache.urlsBaseCache.deleteBackport fixes from 1.0:
omit_if_defaultBackport compatibility fixes from 1.0:
AttributeError due to undetected imports when requests-cache is bundled in a PyInstaller packageAttributeError when attempting to unpickle a CachedSession object, and instead disable pickling by raising a NotImplementedErrorAdd the following for forwards-compatibility with 1.0:
DeprecationWarnings to give an earlier notice for methods deprecated (not removed) in 1.0requests_cache.policy subpackage (will replace requests_cache.cache_control module)BaseCache.contains()BaseCache.delete()BaseCache.filter()CachedSession.settingsBackport fixes from 1.0:
BaseCache.__str__()Backport fixes from 1.0:
install_cache()CachedRequest.path_url propertyBackport fixes from 1.0:
RedisCache for redis-py 4.2 and python <=3.8MongoCache for pymongo 4.1 and python <=3.8bson and standalone bson codec.CorruptGridFile error in GridFS backend~/...) for SQLite and filesystem backendsparams as a positional argument to CachedSession.request()CachedSession.request(..., expire_after=-1)ForwardRef types during deserialization)See all issues and PRs for 0.9
đ Expiration & headers:
Cache-Control request headers by defaultCache-Control: immutableCache-Control: max-age=0 and Expires: 0304 Not Modified response is receivedexpire_after param for CachedSession.send()đž Backends:
đ Performance:
CachedSession.request() and CachedSession.send()đĒ˛ Bugfixes:
BaseCache keyword arguments passed along with a backend instancecache_control=True is used with an expire_after valueCachedResponse serialization behavior when using stdlib pickle in a custom serializerignored_parameters from CachedResponse.url (if used for credentials or other sensitive info)DbDict, etc. so fully qualified imports don't breakSee all issues and PRs for 0.8
đ Expiration & headers:
ETag + If-None-Match headersLast-Modified + If-Modified-Since headers304 Not Modified responsesđž Backends:
FileCache.cache_dir wrapper propertyFileCache.paths() methoduse_cache_dir option to use platform-specific user cache directorypathlib.Path objects for all file pathsSQLiteCache.db_path wrapper propertyuse_memory option and support for in-memory databasesuse_cache_dir option to use platform-specific user cache directorypathlib.Path objects for all file pathsđ Performance:
cattrs by default for optimized serializationâī¸ Request matching:
create_key() to optionally accept parameters for requests.Request instead of a request objectmatch_headers to optionally accept a list of specific headers to matchkey_fn parameterâšī¸ Cache convenience methods:
BaseCache.update() method as a shortcut for exporting to a different cache instanceBaseCache.has_url() and delete_url() to optionally take parameters for requests.Request instead of just a URLđĻ Dependencies:
appdirs as a dependency for easier cross-platform usage of user cache directoriescattrs from optional to required dependencyitsdangerous from required to optional (but recommended) dependencyrequests 2.22+ and urllib3 1.25.5+â ī¸ Backwards-compatible API changes:
The following changes are meant to make certain behaviors more obvious for new users, without breaking existing usage:
Cache-Control: stale-if-error, rename old_data_on_error to stale_if_errorinclude_get_headers to match_headersbackends.sqlite.Db* -> SQLiteCache, SQLiteDict, SQLitePickleDictâ ī¸ Deprecations & removals:
core moduleBaseCache.remove_old_entries() methodredirects.sqlite when using filesystem backendredirects.sqlite would get included in response paths with filesystem backendExpires headers not getting converted to UTCDbCache.clear() to succeed even if the database is corruptedDbDict.bulk_delete() to split the operation into multiple statements to support deleting more items than SQLite's variable limit (999).json, .yaml, .pkl, etc.) by default; can be overridden or disabled with the extension parameter.BaseCache.delete_urls() method to bulk delete multiple responses from the cache based on request URLResponse.next (to get the next request in a redirect chain) when 302 responses are cached directlyCachedResponse.cache_key attributeCachedResponse a non-slotted class to allow client code to set arbitrary attributes on itSee all issues and PRs for 0.7
đ Expiration & headers:
Cache-Control: max-ageCache-Control: no-cacheCache-Control: no-storeCache-Control: max-ageCache-Control: no-storeExpirescache_control option to CachedSession to enable setting expiration with cache headersexpire_after parametersexpire_after=0đž Backends:
DynamoDbDict.__iter__ to return keys instead of valuesboto3.resourceCollection.find_and_modify()pymongo.MongoClientredis.Redisuse_temp option to store files in a temp directorysqlite3.connectđž Serialization:
cattrsultrajsonâī¸ Request matching:
ignored_parameters to also exclude ignored request params, body params, or headers from cached response data (to avoid storing API keys or other credentials)old_data_on_error option to also handle error response codesold_data_on_error is setâšī¸ Convenience methods:
BaseCache.save_response()BaseCache.keys() and values() methodsBaseCache.response_count() method to get an accurate count of responses (excluding invalid and expired)str(CachedResponse)CachedSession, CachedResponse, and BaseCacheBaseCache.urls to only skip invalid responses, not delete them (for better performance)đĻ Dependencies:
requests version of 2.17attrs as a dependency for improved serialization modelscattrs as an optional dependencypip install):requests-cache[all] (to install everything)requests-cache[bson]requests-cache[json]requests-cache[dynamodb]requests-cache[mongodb]requests-cache[redis]đĻ Compatibility and packaging:
requests 2.17 and 2.18requestsfilter_fn() would get called on response.request instead of responseinclude_get_headersdecode_content parameter for CachedResponse.raw.read()Collection.count() with estimated_document_count()BaseCache.urlsBaseCache.remove_old_entries() back, as an alias with a DeprecationWarningaws_access_key_id and aws_secret_access_key kwargs to DynamoDbDictGridFSPickleDict.__delitem__ to raise a KeyError for missing itemslogging.info statements to debug levelfind_packages()See all issues and PRs for 0.6
Thanks to Code Shelter and contributors for making this release possible!
đ Expiration:
CachedSession.expire_after no longer applies retroactively. To reset expiration for previously cached items, see below:CachedSession.remove_expired_responses()datetime-1 (Since None may be ambiguous in some cases)đž Backends:
~/path-to-cache) to database file with db_path paramtimeout parameter'http_cache')đž Serialization:
Note: Due to the following changes, responses cached with previous versions of requests-cache will be invalid. These old responses will be treated as expired, and will be refreshed the next time they are requested. They can also be manually converted or removed, if needed (see notes below).
remove_expired_responses(), also remove responses that are invalid due to updated serialization formatCachedResponse class to wrap cached requests.Response objects, which makes additional cache information available to client codeCachedHTTPResponse class to wrap urllib3.response.HTTPResponse objects, available via CachedResponse.rawBaseCache.urls property to get all URLs persisted in the cacheitsdangerous for more secure serializationOther features:
CacheMixin class to make the features of CachedSession usable as a mixin class, for compatibility with other requests-based libraries.HEAD to default allowable_methodsđ Docs & Tests:
đĒ˛ Bugfixes:
json parameterverify parametercache_nameDbPickleDict initializationCachedSession.cache_disabled if used within another contextmanagerBaseCacheget_cache(), clear(), and remove_expired_responses() so they will do nothing if requests-cache is not installedsave() methodđĻ Dependencies:
itsdangerous as a dependency for secure serializationurl-normalize as a dependency for better request normalization and reducing duplicationsâ ī¸ Deprecations & removals:
core module; all imports should be made from top-level package insteadfrom requests_cache import CachedSessionfrom requests_cache.core will raise a DeprecationWarning, and will be removed in a future releaseBaseCache.remove_old_entries() to remove_expired_responses(), to match its wrapper method CachedSession.remove_expired_responses()Project is now added to Code Shelter
install_cache #61ignore_parameters feature, thanks to @themiurgo and @YetAnotherNerd (#52, #55)expire_after now also accepts timedelta, thanks to @femtotraderinclude_get_headers option)CachedSessionsqlite is not availableresponse.from_cache not set in hooksUnpickleableError for gzip responsesrequests_cache.enabled() context managerRequests 1.x.xCachedSessionRequests 0.14.2sqlite backendallowable_methodssqlite database write operationsfast_save option for sqlite backendMemoryCache -> BaseCache, reduce_response and restore_response moved to BaseCache)connection option for MongoCache