diff options
| -rw-r--r-- | README.md | 31 | ||||
| -rw-r--r-- | docs/user_guide.md | 4 | ||||
| -rw-r--r-- | docs/user_guide/compatibility.md | 2 | ||||
| -rw-r--r-- | docs/user_guide/general.md | 3 | ||||
| -rw-r--r-- | docs/user_guide/headers.md | 32 | ||||
| -rw-r--r-- | pyproject.toml | 6 |
6 files changed, 39 insertions, 39 deletions
@@ -11,7 +11,7 @@ [](https://pypi.org/project/requests-cache) ## Summary -**requests-cache** is a transparent, persistent cache that provides an easy way to get better +**requests-cache** is a persistent HTTP cache that provides an easy way to get better performance with the python [requests](http://python-requests.org) library. <!-- RTD-IGNORE --> @@ -23,7 +23,7 @@ Complete project documentation can be found at [requests-cache.readthedocs.io](h with a [drop-in replacement](https://requests-cache.readthedocs.io/en/stable/user_guide/general.html#sessions) for `requests.Session`, or [install globally](https://requests-cache.readthedocs.io/en/stable/user_guide/general.html#patching) - to add caching to all `requests` functions. + to add transparent caching to all `requests` functions. * 🚀 **Performance:** Get sub-millisecond response times for cached responses. When they expire, you still save time with [conditional requests](https://requests-cache.readthedocs.io/en/stable/user_guide/headers.html#conditional-requests). @@ -31,14 +31,13 @@ Complete project documentation can be found at [requests-cache.readthedocs.io](h [storage backends](https://requests-cache.readthedocs.io/en/stable/user_guide/backends.html) including SQLite, Redis, MongoDB, and DynamoDB; or save responses as plain JSON files, YAML, and more +* 🕗 **Expiration:** Use + [Cache-Control](https://requests-cache.readthedocs.io/en/stable/user_guide/headers.html#cache-control) + and other standard HTTP headers, define your own expiration schedule, keep your cache clutter-free + with backends that natively support TTL, or any combination of strategies * ⚙️ **Customization:** Works out of the box with zero config, but with a robust set of features for configuring and extending the library to suit your needs -* 🕗 **Expiration:** Keep your cache fresh using - [Cache-Control](https://requests-cache.readthedocs.io/en/stable/user_guide/headers.html#cache-control), - eagerly cache everything for long-term storage, use - [URL patterns](https://requests-cache.readthedocs.io/en/stable/user_guide/expiration.html#expiration-with-url-patterns) - for selective caching, or any combination of strategies -* ✔️ **Compatibility:** Can be combined with other +* 🧩 **Compatibility:** Can be combined with other [popular libraries based on requests](https://requests-cache.readthedocs.io/en/stable/user_guide/compatibility.html) ## Quickstart @@ -77,7 +76,6 @@ With caching, the response will be fetched once, saved to `demo_cache.sqlite`, a requests will return the cached response near-instantly. **Patching:** - If you don't want to manage a session object, or just want to quickly test it out in your application without modifying any code, requests-cache can also be installed globally, and all requests will be transparently cached: @@ -89,23 +87,22 @@ requests_cache.install_cache('demo_cache') requests.get('http://httpbin.org/delay/1') ``` -**Configuration:** - -A quick example of some of the options available: +**Settings:** +The default settings work well for most use cases, but there are plenty of ways to customize +caching behavior when needed. Here is a quick example of some of the options available: ```python -# fmt: off from datetime import timedelta from requests_cache import CachedSession session = CachedSession( 'demo_cache', use_cache_dir=True, # Save files in the default user cache dir - cache_control=True, # Use Cache-Control headers for expiration, if available + cache_control=True, # Use Cache-Control response headers for expiration, if available expire_after=timedelta(days=1), # Otherwise expire responses after one day - allowable_methods=['GET', 'POST'], # Cache POST requests to avoid sending the same data twice allowable_codes=[200, 400], # Cache 400 responses as a solemn reminder of your failures - ignored_parameters=['api_key'], # Don't match this param or save it in the cache - match_headers=True, # Match all request headers + allowable_methods=['GET', 'POST'], # Cache whatever HTTP methods you want + ignored_parameters=['api_key'], # Don't match this request param, and redact if from the cache + match_headers=['Accept-Language'], # Cache a different response per language stale_if_error=True, # In case of request errors, use stale cache data if possible ) ``` diff --git a/docs/user_guide.md b/docs/user_guide.md index c36c1e3..4a38ea2 100644 --- a/docs/user_guide.md +++ b/docs/user_guide.md @@ -2,8 +2,8 @@ # {fa}`book` User Guide This section covers the main features of requests-cache. +## The Basics ```{toctree} -:caption: The Basics :maxdepth: 2 user_guide/installation @@ -12,8 +12,8 @@ user_guide/files user_guide/troubleshooting ``` +## Features & Options ```{toctree} -:caption: Features & Options :maxdepth: 2 user_guide/backends diff --git a/docs/user_guide/compatibility.md b/docs/user_guide/compatibility.md index fcd5304..f50e1b0 100644 --- a/docs/user_guide/compatibility.md +++ b/docs/user_guide/compatibility.md @@ -1,5 +1,5 @@ (compatibility)= -# {fa}`plus-square` Usage with other requests-based libraries +# {fa}`puzzle-piece` Compatibility with other libraries This library works by patching and/or extending {py:class}`requests.Session`. Many other libraries out there do the same thing, making it potentially difficult to combine them. diff --git a/docs/user_guide/general.md b/docs/user_guide/general.md index 7047f04..4083794 100644 --- a/docs/user_guide/general.md +++ b/docs/user_guide/general.md @@ -37,7 +37,8 @@ clear out everything at once with {py:meth}`.BaseCache.clear`: (patching)= ## Patching In some situations, it may not be possible or convenient to manage your own session object. In those -cases, you can use {py:func}`.install_cache` to add caching to all `requests` functions: +cases, you can use {py:func}`.install_cache`. This adds fully transparent caching to all `requests` +functions, without the need to modify any existing code: ```python >>> import requests >>> import requests_cache diff --git a/docs/user_guide/headers.md b/docs/user_guide/headers.md index 5d7c696..0ce1ee4 100644 --- a/docs/user_guide/headers.md +++ b/docs/user_guide/headers.md @@ -1,15 +1,9 @@ (headers)= # {fa}`file-code` Cache Headers -Most common request and response headers related to caching are supported, including -[Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) -and [ETags](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag). - -```{note} -requests-cache is not (yet) intended to be strict implementation of HTTP caching according to -[RFC 2616](https://datatracker.ietf.org/doc/html/rfc2616), -[RFC 7234](https://datatracker.ietf.org/doc/html/rfc7234), etc. If there is additional behavior you -would like to see, please create an issue to request it. -``` +Requests-cache supports most common HTTP caching headers, including +[ETags](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag), +[Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control), +and several extensions. (conditional-requests)= ## Conditional Requests @@ -22,19 +16,20 @@ requests-cache repo: ```python >>> # Cache a response that will expire immediately >>> url = 'https://api.github.com/repos/reclosedev/requests-cache' ->>> session = CachedSession(expire_after=0.0001) +>>> session = CachedSession(expire_after=1) >>> session.get(url) ->>> time.sleep(0.0001) +>>> time.sleep(1) >>> # The cached response will still be used until the remote content actually changes >>> response = session.get(url) ->>> print(response.from_cache, response.is_expired) -True, True +>>> print(response.from_cache) +True ``` ## Cache-Control `Cache-Control` **request** headers will always be used if present. This is mainly useful if you are -adding requests-cache to an existing application or library that already uses caching request headers. +adding requests-cache to an existing application or library that already sends requests with cache +headers. `Cache-Control` **response** headers are an opt-in feature. If enabled, these will take priority over any other `expire_after` values. See {ref}`precedence` for the full order of precedence. @@ -44,6 +39,13 @@ To enable this behavior, use the `cache_control` option: ``` ## Supported Headers +Requests-cache implements the majority of private cache behaviors specified by the following RFCs, +with some minor variations: +* [RFC 2616](https://datatracker.ietf.org/doc/html/rfc2616) +* [RFC 5861](https://datatracker.ietf.org/doc/html/rfc5861) +* [RFC 7234](https://datatracker.ietf.org/doc/html/rfc7234) +* [RFC 8246](https://datatracker.ietf.org/doc/html/rfc8246) + The following headers are currently supported: **Request headers:** diff --git a/pyproject.toml b/pyproject.toml index a09e6f4..833b5cb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,7 @@ [tool.poetry] name = "requests-cache" version = "0.10.0" -description = "A transparent persistent cache for the requests library" +description = "A persistent cache for the requests library" authors = ["Roman Haritonov"] maintainers = ["Jordan Cook"] license = "BSD-2-Clause" @@ -9,8 +9,8 @@ readme = "README.md" documentation = "https://requests-cache.readthedocs.io" homepage = "https://github.com/reclosedev/requests-cache" repository = "https://github.com/reclosedev/requests-cache" -keywords = ["requests", "cache", "http", "python-requests", "web", "performance", "sqlite", "redis", - "mongodb", "gridfs", "dynamodb"] +keywords = ["requests", "python-requests", "cache", "http", "web", "performance", + "sqlite", "redis", "mongodb", "gridfs", "dynamodb"] classifiers = [ "Development Status :: 4 - Beta", "Intended Audience :: Developers", |