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

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))