# cached_requests
[](https://github.com/thefcraft/cached_requests)
[](https://badge.fury.io/py/cached_requests)
cached_requests is a Python library that provides a simple and effective caching layer for your web requests. It's built on top of the popular `requests` library and is designed to be a drop-in replacement for `requests.Session`.
## Features
* **Persistent Caching:** Save responses to disk to speed up repeated requests.
* **Automatic Cache Invalidation:** Set a time-to-live (TTL) for your cached responses.
* **Customizable:** Configure cache directories, refresh policies, and more.
* **Easy to Use:** A simple, intuitive API that gets out of your way.
## Installation
Install CacheFlow using pip:
```bash
pip install cached_requests
```
## Quick Start
Here's a simple example of how to use cached_requests:
```python
from cached_requests import CacheSession
from datetime import timedelta
# Create a new session with a cache directory
requests = CacheSession(cache_dir='.cache', refresh_after=timedelta(hours=1)) # or use `from cached_requests import requests`
# Make a request
response = requests.get('https://api.github.com')
# The response is now cached. Subsequent requests to the same URL will be served from the cache.
cached_response = requests.get('https://api.github.com')
print(response.json())
```
## Advanced Usage
### Configuration
You can configure the behavior of cached_requests by passing arguments to the `CacheSession` constructor:
* `cache_dir`: The directory where cached responses will be stored.
* `force_refresh`: If `True`, the cache will be ignored and all requests will be made to the network.
* `refresh_after`: A `timedelta` object that specifies how long a cached response is valid.
* `refresh_on_error`: If `True`, the cache will be refreshed if a cached response resulted in an error.
### Context Manager
You can also use a context manager to temporarily change the configuration:
```python
with requests.configure(force_refresh=True):
# This request will bypass the cache
response = requests.get('https://api.github.com')
```
## Deleting Cache Entries
CacheFlow provides multiple ways to manage your cache.
### Deleting by URL
You can delete cache entries based on a URL pattern:
```python
from cached_requests import delete_cache_by_function
def should_delete(url: str):
return 'github.com' in url
delete_cache_by_function(requests, should_delete)
```
### Deleting by Expiration
You can delete cache entries that are older than a specified timedelta:
```python
from cached_requests import delete_cache_by_expiration
from datetime import timedelta
# Delete all cache entries older than 7 days
delete_cache_by_expiration(requests, timedelta(days=7))
```
## Contributing
Contributions are welcome! If you have a feature request, bug report, or pull request, please open an issue on GitHub.
## License
cached_requests is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
Raw data
{
"_id": null,
"home_page": "https://github.com/thefcraft/cached_requests",
"name": "cached-requests",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "ThefCraft",
"author_email": "sisodiyalaksh@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cf/00/933fb1bb8b59d711144bc3941f04ce1c1c259d1e5a4e8fc03d432c3b7a8e/cached_requests-0.1.5.tar.gz",
"platform": null,
"description": "# cached_requests\n\n[](https://github.com/thefcraft/cached_requests)\n[](https://badge.fury.io/py/cached_requests)\n\ncached_requests is a Python library that provides a simple and effective caching layer for your web requests. It's built on top of the popular `requests` library and is designed to be a drop-in replacement for `requests.Session`.\n\n## Features\n\n* **Persistent Caching:** Save responses to disk to speed up repeated requests.\n* **Automatic Cache Invalidation:** Set a time-to-live (TTL) for your cached responses.\n* **Customizable:** Configure cache directories, refresh policies, and more.\n* **Easy to Use:** A simple, intuitive API that gets out of your way.\n\n## Installation\n\nInstall CacheFlow using pip:\n\n```bash\npip install cached_requests\n```\n\n## Quick Start\n\nHere's a simple example of how to use cached_requests:\n\n```python\nfrom cached_requests import CacheSession\nfrom datetime import timedelta\n\n# Create a new session with a cache directory\nrequests = CacheSession(cache_dir='.cache', refresh_after=timedelta(hours=1)) # or use `from cached_requests import requests`\n\n# Make a request\nresponse = requests.get('https://api.github.com')\n\n# The response is now cached. Subsequent requests to the same URL will be served from the cache.\ncached_response = requests.get('https://api.github.com')\n\nprint(response.json())\n```\n\n## Advanced Usage\n\n### Configuration\n\nYou can configure the behavior of cached_requests by passing arguments to the `CacheSession` constructor:\n\n* `cache_dir`: The directory where cached responses will be stored.\n* `force_refresh`: If `True`, the cache will be ignored and all requests will be made to the network.\n* `refresh_after`: A `timedelta` object that specifies how long a cached response is valid.\n* `refresh_on_error`: If `True`, the cache will be refreshed if a cached response resulted in an error.\n\n### Context Manager\n\nYou can also use a context manager to temporarily change the configuration:\n\n```python\nwith requests.configure(force_refresh=True):\n # This request will bypass the cache\n response = requests.get('https://api.github.com')\n```\n\n## Deleting Cache Entries\n\nCacheFlow provides multiple ways to manage your cache.\n\n### Deleting by URL\n\nYou can delete cache entries based on a URL pattern:\n\n```python\nfrom cached_requests import delete_cache_by_function\ndef should_delete(url: str):\n return 'github.com' in url\n\ndelete_cache_by_function(requests, should_delete)\n```\n### Deleting by Expiration\n\nYou can delete cache entries that are older than a specified timedelta:\n\n```python\nfrom cached_requests import delete_cache_by_expiration\nfrom datetime import timedelta\n# Delete all cache entries older than 7 days\ndelete_cache_by_expiration(requests, timedelta(days=7))\n```\n\n\n## Contributing\n\nContributions are welcome! If you have a feature request, bug report, or pull request, please open an issue on GitHub.\n\n## License\n\ncached_requests is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python library that provides a simple and effective caching layer for web requests.",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://github.com/thefcraft/cached_requests"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cf00933fb1bb8b59d711144bc3941f04ce1c1c259d1e5a4e8fc03d432c3b7a8e",
"md5": "5f8ff1e24c9924359eb71313da3afcf0",
"sha256": "2e85a6aeb61c028ee9e3f1ec8e3eade96208483291e39ea4bc915aa1b444f3b2"
},
"downloads": -1,
"filename": "cached_requests-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "5f8ff1e24c9924359eb71313da3afcf0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10322,
"upload_time": "2025-07-17T07:26:54",
"upload_time_iso_8601": "2025-07-17T07:26:54.912545Z",
"url": "https://files.pythonhosted.org/packages/cf/00/933fb1bb8b59d711144bc3941f04ce1c1c259d1e5a4e8fc03d432c3b7a8e/cached_requests-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 07:26:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "thefcraft",
"github_project": "cached_requests",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cached-requests"
}
JSON
