From ab18e06217a8a1902d1859aae6b033f469b2232b Mon Sep 17 00:00:00 2001
From: Jordan Cook <jordan.cook@pioneer.com>
Date: Sat, 20 Mar 2021 15:19:58 -0500
Subject: 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
---
 examples/basic_usage.py   | 31 +++++++++++++++++++++++++++++++
 examples/expiration.py    | 42 ++++++++++++++++++++++++++++++++++++++++++
 examples/session_patch.py | 36 ++++++++++++++++++++++++++++++++++++
 3 files changed, 109 insertions(+)
 create mode 100644 examples/basic_usage.py
 create mode 100644 examples/expiration.py
 create mode 100644 examples/session_patch.py

(limited to 'examples')

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))
-- 
cgit v1.2.1