Examples¶
This section contains some complete examples that demonstrate the main features of requests-cache.
These can also be found in the examples/ folder on GitHub.
Basic usage (with sessions)¶
An example of testing the cache to prove that it’s not making more requests than expected.
Example code
#!/usr/bin/env python
import time
from requests_cache import CachedSession
def main():
session = CachedSession('example_cache', backend='sqlite')
# The real request will only be made once; afterward, the cached response is used
for i in range(5):
response = session.get('http://httpbin.org/get')
# This is more obvious when calling a slow endpoint
for i in range(5):
response = session.get('http://httpbin.org/delay/2')
# Caching can be disabled if we want to get a fresh page and not cache it
with session.cache_disabled():
print(session.get('http://httpbin.org/ip').text)
# Get some debugging info about the cache
print(session.cache)
print('Cached URLS:', session.cache.urls)
if __name__ == "__main__":
t = time.time()
main()
print('Elapsed: %.3f seconds' % (time.time() - t))
Basic usage (with patching)¶
The same as basic_usage.py
, but using global session patching
Example code
#!/usr/bin/env python
import time
import requests
import requests_cache
# After installation, all requests functions and Session methods will be cached
requests_cache.install_cache('example_cache', backend='sqlite')
def main():
# The real request will only be made once; afterward, the cached response is used
for i in range(5):
response = requests.get('http://httpbin.org/get')
# This is more obvious when calling a slow endpoint
for i in range(5):
response = requests.get('http://httpbin.org/delay/2')
# Caching can be disabled if we want to get a fresh page and not cache it
with requests_cache.disabled():
print(requests.get('http://httpbin.org/ip').text)
# Get some debugging info about the cache
print(requests_cache.get_cache())
print('Cached URLS:', requests_cache.get_cache().urls)
# Uninstall to remove caching from all requests functions
requests_cache.uninstall_cache()
if __name__ == "__main__":
t = time.time()
main()
print('Elapsed: %.3f seconds' % (time.time() - t))
Cache expiration¶
An example of setting expiration for individual requests
Example code
#!/usr/bin/env python
import time
from requests_cache import CachedSession
def main():
session = CachedSession('example_cache', backend='sqlite')
# By default, cached responses never expire
response = session.get('https://httpbin.org/get')
assert not response.from_cache
response = session.get('https://httpbin.org/get')
assert response.from_cache
assert not response.expires
# We can set default expiration for the session using expire_after
session = CachedSession('example_cache', backend='sqlite', expire_after=60)
session.cache.clear()
response = session.get('https://httpbin.org/get')
response = session.get('https://httpbin.org/get')
print('Expiration time:', response.expires)
# This can also be overridden for individual requests
session.cache.clear()
response = session.get('https://httpbin.org/get', expire_after=1)
response = session.get('https://httpbin.org/get')
assert response.from_cache
print('Expiration time:', response.expires)
# After 1 second, the cached value will expired
time.sleep(1.2)
assert response.is_expired
response = session.get('https://httpbin.org/get')
assert not response.from_cache
if __name__ == "__main__":
t = time.perf_counter()
main()
print('Elapsed: %.3f seconds' % (time.perf_counter() - t))
Logging requests¶
An example of testing the cache to prove that it’s not making more requests than expected.
Example code
#!/usr/bin/env python3
from contextlib import contextmanager
from logging import basicConfig, getLogger
from unittest.mock import patch
import requests
from requests_cache import CachedSession
from requests_cache.session import OriginalSession, set_response_defaults
basicConfig(level='INFO')
logger = getLogger('requests_cache.examples')
# Uncomment for more verbose debug output
# getLogger('requests_cache').setLevel('DEBUG')
@contextmanager
def log_requests():
"""Context manager that mocks and logs all non-cached requests"""
real_response = set_response_defaults(requests.get('http://httpbin.org/get'))
with patch.object(OriginalSession, 'send', return_value=real_response) as mock_send:
session = CachedSession('cache-test', backend='sqlite')
session.cache.clear()
yield session
cached_responses = session.cache.responses.values()
logger.debug('All calls to Session._request():')
logger.debug(mock_send.mock_calls)
logger.info(f'Responses cached: {len(cached_responses)}')
logger.info(f'Requests sent: {mock_send.call_count}')
def main():
"""Example usage; replace with any other requests you want to test"""
with log_requests() as session:
for i in range(10):
response = session.get('http://httpbin.org/get')
logger.debug(f'Response {i}: {type(response).__name__}')
if __name__ == '__main__':
main()
Converting an old cache¶
Example of converting data cached in older versions of requests-cache (<=0.5.2) into the current format
Example code
#!/usr/bin/env python
from requests import Response
from requests_cache import CachedResponse, CachedSession
import requests_cache.backends.base
class _Store:
pass
# Add placeholder object used by pickle to deserialize old responses
requests_cache.backends.base._Store = _Store
requests_cache.backends.base._RawStore = _Store
def convert_old_response(cached_response, timestamp):
temp_response = Response()
for field in Response.__attrs__:
setattr(temp_response, field, getattr(cached_response, field, None))
new_response = CachedResponse(temp_response)
new_response.created_at = timestamp
return new_response
def convert_cache(*args, **kwargs):
session = CachedSession(*args, **kwargs)
print(f'Checking {len(session.cache.responses)} cached responses')
with session.cache.responses.bulk_commit():
for key, response in session.cache.responses.items():
if isinstance(response, tuple):
print(f'Converting response {key}')
session.cache.responses[key] = convert_old_response(*response)
print('Conversion complete')
# Example: convert a cache named 'demo_cache.sqlite' in the current directory
if __name__ == '__main__':
convert_cache('demo_cache', backend='sqlite')