Add more notes on deprecated methods

4 files changed, 21 insertions, 9 deletions

diff --git a/HISTORY.md b/HISTORY.md
index 0841a95..b33d2ac 100644
--- a/HISTORY.md
+++ b/HISTORY.md
@@ -111,20 +111,20 @@
 ⚠️ **Deprecations:**
 
 The following methods are deprecated, and will be removed in a future release. The recommended
-replacements are listed below:
-* `BaseCache.remove_expired_responses()`: `BaseCache.delete(expired=True)`
+replacements are listed below. If this causes problems for you, please open an issue to discuss.
 * `CachedSession.remove_expired_responses()`: `BaseCache.delete(expired=True)`
+* `BaseCache.remove_expired_responses()`: `BaseCache.delete(expired=True)`
 * `BaseCache.delete_url()`: `BaseCache.delete(urls=[...])`
 * `BaseCache.delete_urls()`: `BaseCache.delete(urls=[...])`
 * `BaseCache.has_key()`: `BaseCache.contains()`
 * `BaseCache.has_url()`: `BaseCache.contains(url=...)`
-* `BaseCache.keys()`: `BaseCache.filter()`
-* `BaseCache.values()`: `BaseCache.filter()`
-* `BaseCache.response_count()`: `BaseCache.filter()`
+* `BaseCache.keys()`: `BaseCache.responses.keys()` (for all keys), or `BaseCache.filter()` (for filtering options)
+* `BaseCache.values()`: `BaseCache.responses.values()` (for all values), or `BaseCache.filter()` (for filtering options)
+* `BaseCache.response_count()`: `len(BaseCache.responses)` (for all responses), or `BaseCache.filter()` (for filtering options)
 
 ⚠️ **Breaking changes:**
 
-Some relatively minor breaking changes have been made that are not expected to affect most users.
+Some breaking changes have been made that are not expected to affect most users.
 If you encounter a problem not listed here after updating to 1.0, please create a bug report!
 
 * The `BaseCache.urls` property has been replaced with a method that returns a list of URLs
diff --git a/requests_cache/backends/base.py b/requests_cache/backends/base.py
index 083bc71..bc57ca1 100644
--- a/requests_cache/backends/base.py
+++ b/requests_cache/backends/base.py
@@ -251,6 +251,14 @@ class BaseCache:
         return str(self)
 
     # Deprecated methods
+    #
+    # Note: delete_urls(), has_key(), keys(), values(), and response_count() were added relatively
+    # recently and appear to not be widely used, so these will likely be removed within 1 or 2
+    # minor releases.
+    #
+    # The methods delete_url(), has_url() and remove_expired_responses() have been around for longer
+    # and have appeared in various examples in the docs, so these will likely stick around longer
+    # (or could be kept indefinitely if someone really needs them)
     # --------------------
 
     def delete_url(self, url: str, method: str = 'GET', **kwargs):
@@ -310,7 +318,11 @@ class BaseCache:
         self.delete(expired=True, invalid=True)
 
     def values(self, check_expiry: bool = False) -> Iterator[CachedResponse]:
-        warn('BaseCache.values() is deprecated; please use .filter() instead', DeprecationWarning)
+        warn(
+            'BaseCache.values() is deprecated; '
+            'please use .filter() or BaseCache.responses.values() instead',
+            DeprecationWarning,
+        )
         yield from self.filter(expired=not check_expiry)
 
 
diff --git a/tests/compat/test_requests_mock_load_cache.py b/tests/compat/test_requests_mock_load_cache.py
index 2455965..d8d7cc0 100644
--- a/tests/compat/test_requests_mock_load_cache.py
+++ b/tests/compat/test_requests_mock_load_cache.py
@@ -24,7 +24,7 @@ def mock_session():
     adapter = Adapter()
     cache = CachedSession(TEST_DB).cache
 
-    for response in cache.values():
+    for response in cache.responses.values():
         adapter.register_uri(
             response.request.method,
             response.request.url,
diff --git a/tests/compat/test_responses_load_cache.py b/tests/compat/test_responses_load_cache.py
index 793fb0a..4bd72aa 100644
--- a/tests/compat/test_responses_load_cache.py
+++ b/tests/compat/test_responses_load_cache.py
@@ -27,7 +27,7 @@ def get_responses():
     """
     with RequestsMock() as mocker:
         cache = CachedSession(TEST_DB).cache
-        for response in cache.values():
+        for response in cache.responses.values():
             mocker.add(
                 Response(
                     response.request.method,