diff options
author | Jordan Cook <jordan.cook@pioneer.com> | 2022-06-10 16:32:00 -0500 |
---|---|---|
committer | Jordan Cook <jordan.cook@pioneer.com> | 2022-06-10 16:56:23 -0500 |
commit | b812445f77a34d5802c142cb3880463f26ce8e9b (patch) | |
tree | 7200860b18f3c031cf26ba45407e4f90ed3de895 | |
parent | 3854c9ebaf268bce2a6f2339c0fdb088f8c6a686 (diff) | |
download | requests-cache-b812445f77a34d5802c142cb3880463f26ce8e9b.tar.gz |
Update docs and changelog
-rw-r--r-- | HISTORY.md | 4 | ||||
-rw-r--r-- | docs/sample_data/sample_response_binary.json (renamed from docs/sample_data/sample_response.json) | 0 | ||||
-rw-r--r-- | docs/sample_data/sample_response_binary.yaml (renamed from docs/sample_data/sample_response.yaml) | 0 | ||||
-rw-r--r-- | docs/sample_data/sample_response_json.json | 56 | ||||
-rw-r--r-- | docs/sample_data/sample_response_json.yaml | 42 | ||||
-rw-r--r-- | docs/user_guide/backends/filesystem.md | 8 | ||||
-rw-r--r-- | docs/user_guide/serializers.md | 35 |
7 files changed, 134 insertions, 11 deletions
@@ -39,11 +39,15 @@ * Add optional integration with MongoDB TTL to improve performance for removing expired responses * Disabled by default. See 'Backends: MongoDB' docs for details. * DynamoDB: + * Store responses in plain (human-readable) document format instead of fully serialized binary * Create default table in on-demand mode instead of provisioned * Add optional integration with DynamoDB TTL to improve performance for removing expired responses * This is enabled by default, but may be disabled * Filesystem: * The default file format has been changed from pickle to JSON +* Filesystem, MongoDB, and DynamoDB: + * Decode JSON and text response bodies so the saved response can be fully human-readable/editable. + May be disabled with `decode_content=False`. * SQLite, Redis, MongoDB, and GridFS: Close open database connections when `CachedSession` is used as a contextmanager, or if `CachedSession.close()` is called **Request matching & filtering:** 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`. |