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

1 files changed, 42 insertions, 0 deletions

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