diff options
author | Jordan Cook <jordan.cook@pioneer.com> | 2022-06-11 19:25:55 -0500 |
---|---|---|
committer | Jordan Cook <jordan.cook@pioneer.com> | 2022-06-11 19:33:54 -0500 |
commit | c0fc3079c7db0b8d744062e79342613fc8be9367 (patch) | |
tree | 2e2278845da741b34973324df54debf42ead5c1e /docs | |
parent | d04cc094efb44586dd996e6a0554dec99f7d40c6 (diff) | |
download | requests-cache-c0fc3079c7db0b8d744062e79342613fc8be9367.tar.gz |
Update tests and docs
Diffstat (limited to 'docs')
-rw-r--r-- | docs/user_guide/inspection.md | 68 | ||||
-rw-r--r-- | docs/user_guide/matching.md | 3 |
2 files changed, 39 insertions, 32 deletions
diff --git a/docs/user_guide/inspection.md b/docs/user_guide/inspection.md index 26645b2..73f7c29 100644 --- a/docs/user_guide/inspection.md +++ b/docs/user_guide/inspection.md @@ -20,12 +20,12 @@ Examples: >>> from requests_cache import CachedSession >>> session = CachedSession(expire_after=timedelta(days=1)) ->>> # Placeholders are added for non-cached responses +>>> # Placeholder attributes are added for non-cached responses >>> response = session.get('https://httpbin.org/get') >>> print(response.from_cache, response.created_at, response.expires, response.is_expired) False None None None ->>> # Values will be populated for cached responses +>>> # These attributes will be populated for cached responses >>> response = session.get('https://httpbin.org/get') >>> print(response.from_cache, response.created_at, response.expires, response.is_expired) True 2021-01-01 18:00:00 2021-01-02 18:00:00 False @@ -37,49 +37,55 @@ True 2021-01-01 18:00:00 2021-01-02 18:00:00 False ::: ## Cache Contents -You can use `CachedSession.cache.urls` to see all URLs currently in the cache: + +### Checking for responses +Use {py:meth}`.BaseCache.contains` to check if a given request is cached. +Either check with a {py:class}`~requests.models.Request` object: ```python ->>> session = CachedSession() ->>> print(session.cache.urls) -['https://httpbin.org/get', 'https://httpbin.org/stream/100'] -``` +>>> from requests import Request -If needed, you can get more details on cached responses via `CachedSession.cache.responses`, which -is a dict-like interface to the cache backend. See {py:class}`.CachedResponse` for a full list of -attributes available. +>>> request = Request('GET', 'https://httpbin.org/get', params={'k': 'v'}) +>>> print(session.cache.contains(request=request)) +``` -For example, if you wanted to to see all URLs requested with a specific method: +Or with a cache key: ```python ->>> post_urls = [ -... response.url for response in session.cache.responses.values() -... if response.request.method == 'POST' -... ] +>>> print(session.cache.contains('d1e666e9fdfb3f86')) ``` -You can also inspect `CachedSession.cache.redirects`, which maps redirect URLs to keys of the -responses they redirect to. +### Filtering responses +Use {py:meth}`.BaseCache.filter` to get responses with optional filters. By default, it returns all +responses except any invalid ones that would raise an exception: +```python +>>> for response in session.cache.filter(): +>>> print(response) +``` -Additional `keys()` and `values()` wrapper methods are available on {py:class}`.BaseCache` to get -combined keys and responses. +Get unexpired responses: ```python ->>> print('All responses:') ->>> for response in session.cache.values(): +>>> for response in session.cache.filter(expired=False): >>> print(response) +``` ->>> print('All cache keys for redirects and responses combined:') ->>> print(list(session.cache.keys())) +Get keys for **only** expired responses: +```python +>>> expired_responses = session.cache.filter(valid=False, expired=True) +>>> keys = [response.cache_key for response in expired_responses] ``` -Both methods also take a `include_expired` argument. Set to `False` to exclude expired responses: +### Response URLs +You can use {py:meth}`.BaseCache.urls` to see all URLs currently in the cache: ```python ->>> print('All unexpired responses:') ->>> for response in session.cache.values(include_expired=False): ->>> print(response) +>>> session = CachedSession() +>>> print(session.cache.urls()) +['https://httpbin.org/get', 'https://httpbin.org/stream/100'] ``` -Similarly, you can get a count of responses with {py:meth}`.BaseCache.response_count`, and optionally -exclude expired responses: +If needed, you can access all responses via `CachedSession.cache.responses`, which is a dict-like +interface to the cache backend. For example, if you wanted to to see all URLs requested with a specific method: ```python ->>> print(f'Total responses: {session.cache.response_count()}') ->>> print(f'Unexpired responses: {session.cache.response_count(include_expired=False)}') +>>> post_urls = [ +... response.url for response in session.cache.responses.values() +... if response.request.method == 'POST' +... ] ``` diff --git a/docs/user_guide/matching.md b/docs/user_guide/matching.md index 596298b..c368b7d 100644 --- a/docs/user_guide/matching.md +++ b/docs/user_guide/matching.md @@ -77,7 +77,8 @@ cached response: ``` If you want to implement your own request matching, you can provide a cache key function which will -take a {py:class}`~requests.PreparedRequest` plus optional keyword args, and return a string: +take a {py:class}`~requests.PreparedRequest` plus optional keyword args for +{py:func}`~requests.request`, and return a string: ```python def create_key(request: requests.PreparedRequest, **kwargs) -> str: """Generate a custom cache key for the given request""" |