diff options
author | Jordan Cook <jordan.cook@pioneer.com> | 2021-03-20 15:19:58 -0500 |
---|---|---|
committer | Jordan Cook <jordan.cook@pioneer.com> | 2021-03-24 16:46:27 -0500 |
commit | ab18e06217a8a1902d1859aae6b033f469b2232b (patch) | |
tree | 98136dffa4d16ed3d645e2bdee1ac60421001ff7 /examples | |
parent | 78819897213ec3bff57d4c7094fd585dbb8d48d4 (diff) | |
download | requests-cache-ab18e06217a8a1902d1859aae6b033f469b2232b.tar.gz |
More usage examples, formatting, and editing for Readme + Sphinx docs
* Closes #135, #165
* Add a 'Summary' section at the top of the Readme explaining the scope of requests-cache and why you would want to use it
* Add some more info explaining the difference between using `CachedSession` directly vs. patching with `install_cache()`
* Move basic examples from 'User Guide' section into Readme
* Include Readme in Sphinx docs (using `.. mdinclude::`) and remove duplicate sections
* Include Contributing guide in Sphinx docs
* Convert History doc to markdown and include in Sphinx docs
* Use `automod` options to move main cache documentation from `CacheMixin` back to to `CachedSession`, since that's probably where a user will look first
* Add more detailed usage examples to an 'Advanced Usage' section for `CachedSession` options (`filter_fn`, `ignore_parameters`, etc.)
* Update example scripts and move them to `examples/` folder
Diffstat (limited to 'examples')
-rw-r--r-- | examples/basic_usage.py | 31 | ||||
-rw-r--r-- | examples/expiration.py | 42 | ||||
-rw-r--r-- | examples/session_patch.py | 36 |
3 files changed, 109 insertions, 0 deletions
diff --git a/examples/basic_usage.py b/examples/basic_usage.py new file mode 100644 index 0000000..3888681 --- /dev/null +++ b/examples/basic_usage.py @@ -0,0 +1,31 @@ +#!/usr/bin/env python +"""A Simple example using requests-cache with httpbin""" +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)) diff --git a/examples/expiration.py b/examples/expiration.py new file mode 100644 index 0000000..4afa5fa --- /dev/null +++ b/examples/expiration.py @@ -0,0 +1,42 @@ +#!/usr/bin/env python +"""An example of setting expiration for individual requests""" +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)) diff --git a/examples/session_patch.py b/examples/session_patch.py new file mode 100644 index 0000000..8ae900b --- /dev/null +++ b/examples/session_patch.py @@ -0,0 +1,36 @@ +#!/usr/bin/env python +"""The same as `basic_usage.py`, but using global session patching""" +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)) |