Update docs and changelog

6 files changed, 130 insertions, 11 deletions

diff --git a/docs/sample_data/sample_response.json b/docs/sample_data/sample_response_binary.json
index 4b60354..4b60354 100644
--- a/docs/sample_data/sample_response.json
+++ b/docs/sample_data/sample_response_binary.json
diff --git a/docs/sample_data/sample_response.yaml b/docs/sample_data/sample_response_binary.yaml
index 07bc7ca..07bc7ca 100644
--- a/docs/sample_data/sample_response.yaml
+++ b/docs/sample_data/sample_response_binary.yaml
diff --git a/docs/sample_data/sample_response_json.json b/docs/sample_data/sample_response_json.json
new file mode 100644
index 0000000..45ea4e3
--- /dev/null
+++ b/docs/sample_data/sample_response_json.json
@@ -0,0 +1,56 @@
+{
+  "url": "https://httpbin.org/json",
+  "status_code": 200,
+  "reason": "OK",
+  "_decoded_content": {
+    "slideshow": {
+      "author": "Yours Truly",
+      "date": "date of publication",
+      "slides": [
+        {
+          "title": "Wake up to WonderWidgets!",
+          "type": "all"
+        },
+        {
+          "items": [
+            "Why <em>WonderWidgets<\/em> are great",
+            "Who <em>buys<\/em> WonderWidgets"
+          ],
+          "title": "Overview",
+          "type": "all"
+        }
+      ],
+      "title": "Sample Slide Show"
+    }
+  },
+  "cache_key": "4dc151d95200ec91fa77021989f5194e9be47e87f8f228306f3a8d5434b9e547",
+  "created_at": "2021-07-21T22:34:50.343095",
+  "elapsed": 0.242198,
+  "encoding": "utf-8",
+  "headers": {
+    "Date": "Wed, 21 Jul 2021 22:34:50 GMT",
+    "Content-Type": "application/json",
+    "Content-Length": "429",
+    "Connection": "keep-alive",
+    "Server": "gunicorn/19.9.0",
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Credentials": "true"
+  },
+  "request": {
+    "body": "PH%2y",
+    "headers": {
+      "User-Agent": "python-requests/2.26.0",
+      "Accept-Encoding": "gzip, deflate",
+      "Accept": "*/*",
+      "Connection": "keep-alive"
+    },
+    "method": "GET",
+    "url": "https://httpbin.org/json"
+  },
+  "raw": {
+    "decode_content": false,
+    "reason": "OK",
+    "status": 200,
+    "version": 11
+  }
+}
diff --git a/docs/sample_data/sample_response_json.yaml b/docs/sample_data/sample_response_json.yaml
new file mode 100644
index 0000000..4949e31
--- /dev/null
+++ b/docs/sample_data/sample_response_json.yaml
@@ -0,0 +1,42 @@
+url: https://httpbin.org/json
+status_code: 200
+reason: OK
+_decoded_content:
+  slideshow:
+    author: Yours Truly
+    date: date of publication
+    slides:
+    - title: Wake up to WonderWidgets!
+      type: all
+    - items:
+      - Why <em>WonderWidgets</em> are great
+      - Who <em>buys</em> WonderWidgets
+      title: Overview
+      type: all
+    title: Sample Slide Show
+created_at: '2021-07-21T22:32:17.592974'
+elapsed: 0.187586
+encoding: utf-8
+headers:
+  Access-Control-Allow-Credentials: 'true'
+  Access-Control-Allow-Origin: '*'
+  Connection: keep-alive
+  Content-Length: '308'
+  Content-Type: application/json
+  Date: Wed, 21 Jul 2021 22:32:17 GMT
+  Server: gunicorn/19.9.0
+request:
+  method: GET
+  url: https://httpbin.org/json
+  body: !!binary |
+    Tm9uZQ==
+  headers:
+    Accept: '*/*'
+    Accept-Encoding: gzip, deflate
+    Connection: keep-alive
+    User-Agent: python-requests/2.26.0
+raw:
+  decode_content: false
+  reason: OK
+  status: 200
+  version: 11
diff --git a/docs/user_guide/backends/filesystem.md b/docs/user_guide/backends/filesystem.md
index 07e41c4..baab5f0 100644
--- a/docs/user_guide/backends/filesystem.md
+++ b/docs/user_guide/backends/filesystem.md
@@ -32,15 +32,17 @@ YAML files (requires `pyyaml`):
 ```python
 >>> session = CachedSession('~/http_cache', backend='filesystem', serializer='yaml')
 >>> session.get('https://httpbin.org/get')
->>> print(list(session.cache.paths()))
-> ['/home/user/http_cache/4dc151d95200ec.yaml']
 ```
 
 ## Cache Files
 - See {ref}`files` for general info on specifying cache paths
 - The path for a given response will be in the format `<cache_name>/<cache_key>`
 - Redirects are stored in a separate SQLite database, located at `<cache_name>/redirects.sqlite`
-- Use {py:meth}`.FileCache.paths` to get a list of all cached response paths
+- Use {py:meth}`.FileCache.paths` to get a list of all cached response paths:
+```python
+>>> print(list(session.cache.paths()))
+> ['/home/user/http_cache/4dc151d95200ec.yaml']
+```
 
 ## Performance and Limitations
 - Write performance will vary based on the serializer used, in the range of roughly 1-3ms per write.
diff --git a/docs/user_guide/serializers.md b/docs/user_guide/serializers.md
index b2bae92..efeec10 100644
--- a/docs/user_guide/serializers.md
+++ b/docs/user_guide/serializers.md
@@ -5,12 +5,10 @@
 ![](../_static/file-yaml_32px.png)
 ![](../_static/file-toml_32px.png)
 
-By default, responses are serialized using {py:mod}`pickle`, but some alternative serializers are
-also included. These are mainly intended for use with {py:class}`.FileCache`, but are compatible
-with the other backends as well.
+Some alternative serializers are included, mainly intended for use with {py:class}`.FileCache`.
 
 :::{note}
-Some serializers require additional dependencies
+Some of these serializers require additional dependencies, listed in the sections below.
 :::
 
 ## Specifying a Serializer
@@ -26,9 +24,15 @@ Usage:
 >>> session = CachedSession('my_cache', serializer='json')
 ```
 
-:::{admonition} Example JSON-serialized Response
+:::{admonition} Example JSON-serialized Response (with decoded JSON content)
 :class: toggle
-```{literalinclude} ../sample_data/sample_response.json
+```{literalinclude} ../sample_data/sample_response_json.json
+:language: JSON
+```
+:::
+:::{admonition} Example JSON-serialized Response (with binary content)
+:class: toggle
+```{literalinclude} ../sample_data/sample_response_binary.json
 :language: JSON
 ```
 :::
@@ -47,9 +51,15 @@ Usage:
 >>> session = CachedSession('my_cache', serializer='yaml')
 ```
 
-:::{admonition} Example YAML-serialized Response
+:::{admonition} Example YAML-serialized Response (with decoded JSON content)
+:class: toggle
+```{literalinclude} ../sample_data/sample_response_json.yaml
+:language: YAML
+```
+:::
+:::{admonition} Example YAML-serialized Response (with binary content)
 :class: toggle
-```{literalinclude} ../sample_data/sample_response.yaml
+```{literalinclude} ../sample_data/sample_response_binary.yaml
 :language: YAML
 ```
 :::
@@ -82,6 +92,15 @@ MongoDB dependencies:
 pip install requests-cache[bson]
 ```
 
+## Response Content Format
+By default, any JSON or text response body will be decoded, so the response is fully
+human-readable/editable. Other content types will be saved as binary data. To save _all_ content as binary, set ``decode_content=False``:
+```python
+>>> backend = FileCache(decode_content=False)
+>>> session = CachedSession('http_cache', backend=backend)
+```
+
+
 ## Serializer Security
 See {ref}`security` for recommended setup steps for more secure cache serialization, particularly
 when using {py:mod}`pickle`.