From 2aebfe37e27a4e85c1640a0fe4d1632ba19a6fbf Mon Sep 17 00:00:00 2001 From: Jordan Cook Date: Thu, 25 Mar 2021 09:44:31 -0500 Subject: Move 'Security' section to a separate page, link from Readme, and add itsdangerous to default package dependencies --- README.md | 47 ++++++++++++++++++++++++++--------------------- 1 file changed, 26 insertions(+), 21 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 07dfbca..4cb531e 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# requests-cache +# Requests-Cache [![Build](https://github.com/reclosedev/requests-cache/actions/workflows/build.yml/badge.svg)](https://github.com/reclosedev/requests-cache/actions/workflows/build.yml) [![Coverage](https://coveralls.io/repos/github/reclosedev/requests-cache/badge.svg?branch=master)](https://coveralls.io/github/reclosedev/requests-cache?branch=master) [![Documentation](https://img.shields.io/readthedocs/requests-cache/latest)](https://requests-cache.readthedocs.io/en/latest/) @@ -23,26 +23,27 @@ Install with pip: pip install requests-cache ``` -Requirements: -Requires python 3.6+. -You may need additional dependencies depending on which backend you want to use. -To install with extra dependencies for all supported backends: -```bash -pip install requests-cache[backends] -``` +**Requirements:** +* Requires python 3.6+. +* You may need additional dependencies depending on which backend you want to use. To install with + extra dependencies for all supported backends: -See [Contributing Guide](https://github.com/reclosedev/requests-cache/blob/master/CONTRIBUTING.md) -for setup info for local development. + ```bash + pip install requests-cache[backends] + ``` -## Full Examples -* You can find a working example at Real Python: -[Caching External API Requests](https://realpython.com/blog/python/caching-external-api-requests) -* There are some additional examples in the [examples/](https://github.com/reclosedev/requests-cache/tree/master/examples) folder +**Optional Setup Steps:** +* See [Security](https://requests-cache.readthedocs.io/en/latest/security.html) for recommended + setup for more secure cache serialization. +* See [Contributing Guide](https://requests-cache.readthedocs.io/en/latest/contributing.html) + for setup info for local development. ## General Usage There are two main ways of using `requests-cache`: -* Using [CachedSession](https://requests-cache.readthedocs.io/en/latest/api.html#requests_cache.core.CachedSession) (recommended) -* Globally patching `requests` using [install_cache](https://requests-cache.readthedocs.io/en/latest/api.html#requests_cache.core.install_cache) +* **Sessions:** Use [requests_cache.CachedSession](https://requests-cache.readthedocs.io/en/latest/api.html#requests_cache.core.CachedSession) + in place of [requests.Session](https://requests.readthedocs.io/en/master/user/advanced/#session-objects) (recommended) +* **Patching:** Globally patch `requests` using + [requests_cache.install_cache](https://requests-cache.readthedocs.io/en/latest/api.html#requests_cache.core.install_cache) ### Sessions `CachedSession` wraps `requests.Session` with caching features, and otherwise behaves the same as a @@ -60,9 +61,6 @@ The URL in this example adds a delay of 1 second, but all 100 requests will comp second. The response will be fetched once, saved to `demo_cache.sqlite`, and subsequent requests will return the cached response near-instantly. -There are many ways to customize caching behavior; see -[Advanced Usage](https://requests-cache.readthedocs.io/en/latest/advanced_usage.html) for details. - ### Patching Patching with `requests_cache.install_cache()` will add caching to all `requests` functions: ```python @@ -126,7 +124,7 @@ You can also set expiration on a per-request basis, which will override any sess session.get('http://httpbin.org/get', expire_after=360) ``` -If a per-session expiration is set but you want to temporarily disable it, use ```-1```: +If a per-session expiration is set but you want to temporarily disable it, use `-1`: ```python # Never expire session.get('http://httpbin.org/get', expire_after=-1) @@ -147,9 +145,16 @@ Or, to revalidate the cache with a new expiration: session.remove_expired_responses(expire_after=360) ``` +## More Features & Examples +* You can find a working example at Real Python: + [Caching External API Requests](https://realpython.com/blog/python/caching-external-api-requests) +* There are some additional examples in the [examples/](https://github.com/reclosedev/requests-cache/tree/master/examples) folder +* See [Advanced Usage](https://requests-cache.readthedocs.io/en/latest/advanced_usage.html) for + details on customizing cache behavior and other features beyond the basics. + ## Related Projects If `requests-cache` isn't quite what you need, you can help make it better! See the -[Contributing Guide](https://github.com/reclosedev/requests-cache/blob/master/CONTRIBUTING.md) +[Contributing Guide](https://requests-cache.readthedocs.io/en/latest/contributing.html) for details. You can also check out these other python cache projects: -- cgit v1.2.1