Add 'url' argument to BaseCache.contains() and delete() for similarity to has_url() and delete_url()

2 files changed, 19 insertions, 7 deletions

diff --git a/docs/user_guide/expiration.md b/docs/user_guide/expiration.md
index ef1d9e1..4c9fc88 100644
--- a/docs/user_guide/expiration.md
+++ b/docs/user_guide/expiration.md
@@ -181,15 +181,20 @@ 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>`:
+Finally, you can delete individual 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'})
+
+# Delete a simple GET request by URL
+>>> session.cache.delete(urls=['https://httpbin.org/json'])
+
+# Delete by additional request values
+>>> request_1 = Request('GET', 'https://httpbin.org/get', params={'key': 'value'})
+>>> request_2 = Request('GET', 'https://httpbin.org/get', headers={'header': 'value'})
 >>> session.cache.delete(requests=[request_1, request_2])
-```
 
-```python
+# Delete by cache key
 >>> session.cache.delete('e25f7e6326966e82')
 ```
 
diff --git a/docs/user_guide/inspection.md b/docs/user_guide/inspection.md
index 873f6a3..9f9991e 100644
--- a/docs/user_guide/inspection.md
+++ b/docs/user_guide/inspection.md
@@ -42,7 +42,14 @@ True 2021-01-01 18:00:00 2021-01-02 18:00:00 False
 
 ### 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:
+
+Check if a specific URL is cached:
+```python
+>>> print(session.cache.contains(url='https://httpbin.org/get'))
+```
+
+To match additional request values (parameters, headers, etc), you can pass a
+{py:class}`~requests.models.Request` object instead:
 ```python
 >>> from requests import Request
 
@@ -50,7 +57,7 @@ Either check with a {py:class}`~requests.models.Request` object:
 >>> print(session.cache.contains(request=request))
 ```
 
-Or with a cache key:
+You can also check for a specific cache key:
 ```python
 >>> print(session.cache.contains('d1e666e9fdfb3f86'))
 ```