Merge pull request #696 from requests-cache/delete-docs

Add docs and wrapper function for BaseCache.delete()

4 files changed, 61 insertions, 16 deletions

diff --git a/docs/user_guide/expiration.md b/docs/user_guide/expiration.md
index 9d0ec9c..ef1d9e1 100644
--- a/docs/user_guide/expiration.md
+++ b/docs/user_guide/expiration.md
@@ -143,27 +143,36 @@ Or specify a maximum staleness value you are willing to accept:
 session = CachedSession(stale_while_revalidate=timedelta(minutes=5))
 ```
 
-## Removing Expired Responses
+## Removing Responses
+For better read performance, expired responses won't be removed immediately by default.
+Instead, they will be replaced the next time they are requested.
 
+You can manually delete responses according to various conditions, and some backends support
+automatic removal.
+
+(manual_removal)=
 ### Manual Removal
-For better read performance, expired responses won't be removed immediately, but will be removed
-(or replaced) the next time they are requested.
 
-To manually clear all expired responses, use
-{py:meth}`.BaseCache.remove`:
+To delete **all** cached responses, use {py:meth}`.BaseCache.clear`:
+```python
+>>> session.cache.clear()
+```
+
+To delete expired responses, use {py:meth}`.BaseCache.delete`:
 ```python
->>> session.cache.remove(expired=True)
+>>> session.cache.delete(expired=True)
 ```
 
-Or, if you are using {py:func}`.install_cache`:
+Or, if you have patched ``requests`` using {py:func}`.install_cache`:
 ```python
->>> requests_cache.remove_expired_responses()
+>>> import requests_cache
+>>> requests_cache.delete(expired=True)
 ```
 
 You can also remove responses older than a certain time:
 ```python
 # Remove responses older than 7 days
-session.cache.remove(older_than=timedelta(days=7))
+session.cache.delete(older_than=timedelta(days=7))
 ```
 
 Or apply a new expiration value to previously cached responses:
@@ -172,6 +181,18 @@ Or apply a new expiration value to previously cached responses:
 >>> session.cache.reset_expiration(timedelta(days=30))
 ```
 
+Finally, you can delete responses matching specific requests or {ref}`cache keys <custom-matching>`:
+```python
+>>> from requests import Request
+>>> request_1 = Request('GET', 'https://httpbin.org/get')
+>>> request_2 = Request('GET', 'https://httpbin.org/get', params={'key': 'value'})
+>>> session.cache.delete(requests=[request_1, request_2])
+```
+
+```python
+>>> session.cache.delete('e25f7e6326966e82')
+```
+
 (ttl)=
 ### Automatic Removal
 The following backends have native TTL support, which can be used to automatically remove expired
diff --git a/docs/user_guide/inspection.md b/docs/user_guide/inspection.md
index 98db7e6..873f6a3 100644
--- a/docs/user_guide/inspection.md
+++ b/docs/user_guide/inspection.md
@@ -75,6 +75,10 @@ Get keys for **only** expired responses:
 >>> keys = [response.cache_key for response in expired_responses]
 ```
 
+### Deleting responses
+Use {py:meth}`.BaseCache.delete` to manually delete responses. See {ref}`manual_removal` for
+examples.
+
 ### Response URLs
 You can use {py:meth}`.BaseCache.urls` to see all URLs currently in the cache:
 ```python
diff --git a/requests_cache/patcher.py b/requests_cache/patcher.py
index 30ba908..137e928 100644
--- a/requests_cache/patcher.py
+++ b/requests_cache/patcher.py
@@ -10,6 +10,7 @@
 from contextlib import contextmanager
 from logging import getLogger
 from typing import Optional, Type
+from warnings import warn
 
 import requests
 
@@ -106,11 +107,22 @@ def clear():
         get_cache().clear()
 
 
-def remove_expired_responses():
-    """Remove expired and invalid responses from the cache"""
+def delete(*args, **kwargs):
+    """Remove responses from the cache according one or more conditions.
+    See :py:meth:`.BaseCache.delete for usage details.
+    """
     session = requests.Session()
     if isinstance(session, CachedSession):
-        session.cache.delete(expired=True)
+        session.cache.delete(*args, **kwargs)
+
+
+def remove_expired_responses():
+    """Remove expired responses from the cache"""
+    warn(
+        'remove_expired_responses() is deprecated; please use delete() instead',
+        DeprecationWarning,
+    )
+    delete(expired=True)
 
 
 def _patch_session_factory(session_factory: Type[OriginalSession] = CachedSession):
diff --git a/tests/unit/test_patcher.py b/tests/unit/test_patcher.py
index 5a99d6a..ceb2a4c 100644
--- a/tests/unit/test_patcher.py
+++ b/tests/unit/test_patcher.py
@@ -82,14 +82,22 @@ def test_is_installed():
 
 
 @patch.object(BaseCache, 'delete')
-def test_remove_expired_responses(mock_delete):
+def test_delete__expired_responses(mock_delete):
     requests_cache.install_cache(backend='memory', expire_after=360)
-    requests_cache.remove_expired_responses()
+    requests_cache.delete(expired=True)
     assert mock_delete.called is True
     requests_cache.uninstall_cache()
 
 
 @patch.object(BaseCache, 'delete')
-def test_remove_expired_responses__cache_not_installed(mock_delete):
-    requests_cache.remove_expired_responses()
+def test_delete__cache_not_installed(mock_delete):
+    requests_cache.delete(expired=True)
     assert mock_delete.called is False
+
+
+@patch.object(BaseCache, 'delete')
+def test_remove_expired_responses(mock_delete):
+    requests_cache.install_cache(backend='memory', expire_after=360)
+    requests_cache.remove_expired_responses()
+    assert mock_delete.called is True
+    requests_cache.uninstall_cache()