summaryrefslogtreecommitdiff
path: root/docs/user_guide
diff options
context:
space:
mode:
authorJordan Cook <jordan.cook@pioneer.com>2022-06-17 16:02:17 -0500
committerJordan Cook <jordan.cook@pioneer.com>2022-06-17 16:30:18 -0500
commit2bcd6df0fd80205a03aa4787ddf411e9632c4fed (patch)
treec8b2b43a6b7a97124f0343004a87ef46975f7305 /docs/user_guide
parent795c785eae7dbd04419bec5a0d2aec278570a948 (diff)
downloadrequests-cache-2bcd6df0fd80205a03aa4787ddf411e9632c4fed.tar.gz
Use sphinx-design dropdown instead of custom CSS/JS
Diffstat (limited to 'docs/user_guide')
-rw-r--r--docs/user_guide/advanced_requests.md14
-rw-r--r--docs/user_guide/backends.md7
-rw-r--r--docs/user_guide/backends/dynamodb.md22
-rw-r--r--docs/user_guide/backends/mongodb.md6
-rw-r--r--docs/user_guide/compatibility.md40
-rw-r--r--docs/user_guide/filtering.md3
-rw-r--r--docs/user_guide/inspection.md8
-rw-r--r--docs/user_guide/serializers.md42
8 files changed, 100 insertions, 42 deletions
diff --git a/docs/user_guide/advanced_requests.md b/docs/user_guide/advanced_requests.md
index ac9e204..2a3c185 100644
--- a/docs/user_guide/advanced_requests.md
+++ b/docs/user_guide/advanced_requests.md
@@ -8,8 +8,11 @@ Requests has an [event hook](https://requests.readthedocs.io/en/master/user/adva
system that can be used to add custom behavior into different parts of the request process.
It can be used, for example, for request throttling:
-:::{admonition} Example code
-:class: toggle
+:::{dropdown} Example
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-code
+
```python
>>> import time
>>> import requests
@@ -38,8 +41,11 @@ can use the same code to iterate over both cached and non-cached requests. Cache
will have already been read (i.e., consumed), but will be available for re-reading so it behaves like
the original streamed response:
-:::{admonition} Example code
-:class: toggle
+:::{dropdown} Example
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-code
+
```python
>>> from requests_cache import CachedSession
diff --git a/docs/user_guide/backends.md b/docs/user_guide/backends.md
index 7f85fa7..8238665 100644
--- a/docs/user_guide/backends.md
+++ b/docs/user_guide/backends.md
@@ -117,8 +117,11 @@ Or, using backend classes directly:
## Custom Backends
If the built-in backends don't suit your needs, you can create your own by making subclasses of {py:class}`.BaseCache` and {py:class}`.BaseStorage`:
-:::{admonition} Example code
-:class: toggle
+:::{dropdown} Example
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-code
+
```python
>>> from requests_cache import CachedSession
>>> from requests_cache.backends import BaseCache, BaseStorage
diff --git a/docs/user_guide/backends/dynamodb.md b/docs/user_guide/backends/dynamodb.md
index ee06aca..7761903 100644
--- a/docs/user_guide/backends/dynamodb.md
+++ b/docs/user_guide/backends/dynamodb.md
@@ -42,15 +42,21 @@ documents. Response data can then be easily viewed via the
[AWS Console](https://aws.amazon.com/console/).
Here is an example of responses listed under **DynamoDB > Tables > Explore Items:**
-:::{admonition} Screenshot
-:class: toggle
+:::{dropdown} Screenshot
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-media
+
```{image} ../../_static/dynamodb_items.png
```
:::
And here is an example response:
-:::{admonition} Screenshot
-:class: toggle
+:::{dropdown} Screenshot
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-media
+
```{image} ../../_static/dynamodb_response.png
```
:::
@@ -96,8 +102,12 @@ Here are the details you will need:
- Range key (aka sort key): `key`
### Example CloudFormation Template
-:::{admonition} Example: [cloudformation.yml](https://github.com/requests-cache/requests-cache/blob/main/examples/cloudformation.yml)
-:class: toggle
+:::{dropdown} Example
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-code
+
+[cloudformation.yml](https://github.com/requests-cache/requests-cache/blob/main/examples/cloudformation.yml)
```{literalinclude} ../../../examples/cloudformation.yml
:language: yaml
```
diff --git a/docs/user_guide/backends/mongodb.md b/docs/user_guide/backends/mongodb.md
index 4b504cc..3561f01 100644
--- a/docs/user_guide/backends/mongodb.md
+++ b/docs/user_guide/backends/mongodb.md
@@ -41,8 +41,10 @@ Response data can be easily viewed via the
Here is an example response viewed in
[MongoDB for VSCode](https://code.visualstudio.com/docs/azure/mongodb):
-:::{admonition} Screenshot
-:class: toggle
+:::{dropdown} Screenshot
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-media
```{image} ../../_static/mongodb_vscode.png
```
:::
diff --git a/docs/user_guide/compatibility.md b/docs/user_guide/compatibility.md
index 12f2203..c7284fb 100644
--- a/docs/user_guide/compatibility.md
+++ b/docs/user_guide/compatibility.md
@@ -117,8 +117,11 @@ For example, if you are using {py:func}`.install_cache` in your application and
requests-mock [pytest fixture](https://requests-mock.readthedocs.io/en/latest/pytest.html) in your
tests, you could wrap it in another fixture that uses {py:func}`.uninstall_cache` or
{py:func}`.disabled`:
-:::{admonition} Example: test_requests_mock_disable_cache.py
-:class: toggle
+:::{dropdown} Example
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-code
+
```{literalinclude} ../../tests/compat/test_requests_mock_disable_cache.py
```
:::
@@ -141,8 +144,12 @@ Or if you use a `CachedSession` object, you could replace it with a regular `Ses
If you want both caching and mocking features at the same time, you can attach requests-mock's
[adapter](https://requests-mock.readthedocs.io/en/latest/adapter.html) to a `CachedSession`:
-:::{admonition} Example: `test_requests_mock_combine_cache.py`
-:class: toggle
+:::{dropdown} Example
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-code
+
+`test_requests_mock_combine_cache.py`
```{literalinclude} ../../tests/compat/test_requests_mock_combine_cache.py
```
:::
@@ -157,8 +164,12 @@ This has the advantage of only using request-mock's behavior for
```
To turn that into a complete example:
-:::{admonition} Example: `test_requests_mock_load_cache.py`
-:class: toggle
+:::{dropdown} Example
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-code
+
+`test_requests_mock_load_cache.py`
```{literalinclude} ../../tests/compat/test_requests_mock_load_cache.py
```
:::
@@ -167,8 +178,12 @@ To turn that into a complete example:
Usage with the [responses](https://github.com/getsentry/responses) library is similar to the
requests-mock examples above.
-:::{admonition} Example: `test_responses_load_cache.py`
-:class: toggle
+:::{dropdown} Example
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-code
+
+`test_responses_load_cache.py`
```{literalinclude} ../../tests/compat/test_responses_load_cache.py
```
:::
@@ -177,8 +192,13 @@ requests-mock examples above.
If you would like to reuse your cached response data for unit tests, one option is to convert your
cache into a format compatible with VCR-vased libraries like
[vcrpy](https://github.com/kevin1024/vcrpy) and [betamax](https://github.com/betamaxpy/betamax).
-:::{admonition} Example: `vcr.py`
-:class: toggle
+
+:::{dropdown} Example
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-code
+
+`vcr.py`
```{literalinclude} ../../examples/vcr.py
:lines: 7-
```
diff --git a/docs/user_guide/filtering.md b/docs/user_guide/filtering.md
index 885b991..e7a5c06 100644
--- a/docs/user_guide/filtering.md
+++ b/docs/user_guide/filtering.md
@@ -58,8 +58,6 @@ function via the `filter_fn` param. This can by any function that takes a
should be cached. It will be applied to both new responses (on write) and previously cached
responses (on read):
-:::{admonition} Example code
-:class: toggle
```python
>>> from sys import getsizeof
>>> from requests_cache import CachedSession
@@ -70,7 +68,6 @@ responses (on read):
>>> session = CachedSession(filter_fn=filter_by_size)
```
-:::
```{note}
`filter_fn()` will be used **in addition to** other filtering options.
diff --git a/docs/user_guide/inspection.md b/docs/user_guide/inspection.md
index cc7bb39..98db7e6 100644
--- a/docs/user_guide/inspection.md
+++ b/docs/user_guide/inspection.md
@@ -13,9 +13,11 @@ The following attributes are available on responses:
{ref}`expiration` for details)
- `is_expired`: indicates if the cached response is expired (if, for example, an old response was returned due to a request error)
-Examples:
-:::{admonition} Example code
-:class: toggle
+:::{dropdown} Examples
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-code
+
```python
>>> from requests_cache import CachedSession
>>> session = CachedSession(expire_after=timedelta(days=1))
diff --git a/docs/user_guide/serializers.md b/docs/user_guide/serializers.md
index 77980b0..bbc85f3 100644
--- a/docs/user_guide/serializers.md
+++ b/docs/user_guide/serializers.md
@@ -26,14 +26,20 @@ Usage:
>>> session = CachedSession('my_cache', serializer='json')
```
-:::{admonition} Example JSON-serialized Response (with decoded JSON content)
-:class: toggle
+:::{dropdown} Example JSON-serialized Response (with decoded JSON content)
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-code
+
```{literalinclude} ../sample_data/sample_response_json.json
:language: JSON
```
:::
-:::{admonition} Example JSON-serialized Response (with binary content)
-:class: toggle
+:::{dropdown} Example JSON-serialized Response (with binary content)
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-code
+
```{literalinclude} ../sample_data/sample_response_binary.json
:language: JSON
```
@@ -53,14 +59,20 @@ Usage:
>>> session = CachedSession('my_cache', serializer='yaml')
```
-:::{admonition} Example YAML-serialized Response (with decoded JSON content)
-:class: toggle
+:::{dropdown} Example YAML-serialized Response (with decoded JSON content)
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-code
+
```{literalinclude} ../sample_data/sample_response_json.yaml
:language: YAML
```
:::
-:::{admonition} Example YAML-serialized Response (with binary content)
-:class: toggle
+:::{dropdown} Example YAML-serialized Response (with binary content)
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-code
+
```{literalinclude} ../sample_data/sample_response_binary.yaml
:language: YAML
```
@@ -128,8 +140,11 @@ similar methods with different names (e.g. `compress` / `decompress`), those can
{py:class}`.Stage`.
For example, a compressed pickle serializer can be built as:
-:::{admonition} Example code
-:class: toggle
+:::{dropdown} Example
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-code
+
```python
>>> import gzip
>>> from requests_cache import CachedSession, SerializerPipeline, Stage, pickle_serializer
@@ -151,8 +166,11 @@ the majority of the work here, and some pre-configured converters are included f
formats in the {py:mod}`.preconf` module.
For example, a compressed JSON pipeline could be built as follows:
-:::{admonition} Example code
-:class: toggle
+:::{dropdown} Example
+:animate: fade-in-slide-down
+:color: primary
+:icon: file-code
+
```python
>>> import json, gzip
>>> from requests_cache import CachedSession, SerializerPipeline, Stage, json_serializer, utf8_encoder