Add compatibility example with requests-ratelimiter

1 files changed, 29 insertions, 2 deletions

diff --git a/docs/user_guide/compatibility.md b/docs/user_guide/compatibility.md
index 354f572..98d6481 100644
--- a/docs/user_guide/compatibility.md
+++ b/docs/user_guide/compatibility.md
@@ -40,7 +40,7 @@ Or if you are using {py:func}`.install_cache`, you can use the `session_factory`
 
 The same approach can be used with other libraries that subclass {py:class}`requests.Session`.
 
-## Requests-futures
+## Requests-Futures
 Some libraries, including [requests-futures](https://github.com/ross/requests-futures),
 support wrapping an existing session object:
 ```python
@@ -51,6 +51,33 @@ In this case, `FutureSession` must wrap `CachedSession` rather than the other wa
 `FutureSession` returns (as you might expect) futures rather than response objects.
 See [issue #135](https://github.com/reclosedev/requests-cache/issues/135) for more notes on this.
 
+## Requests-Ratelimiter
+[requests-ratelimiter](https://github.com/JWCook/requests-ratelimiter) adds rate-limiting to
+requests via the [pyrate-limiter](https://github.com/vutran1710/PyrateLimiter) library. It also
+provides a mixin, but note that the inheritance order is important: If rate-limiting is applied
+_after_ caching, you get the added benefit of not counting cache hits against your rate limit.
+```python
+from pyrate_limiter import RedisBucket, RequestRate, Duration
+from requests import Session
+from requests_cache import CacheMixin, RedisCache
+from requests_ratelimiter import LimiterMixin
+
+
+class CachedLimiterSession(CacheMixin, LimiterMixin, Session):
+    """Session class with caching and rate-limiting behavior. Accepts arguments for both
+    LimiterSession and CachedSession.
+    """
+
+
+# Limit non-cached requests to 5 requests per second, with unlimited cached requests
+# Optionally use Redis as both the bucket backend and the cache backend
+session = CachedLimiterSession(
+    rates=RequestRate(5, Duration.SECOND),
+    bucket_class=RedisBucket,
+    backend=RedisCache(),
+)
+```
+
 ## Internet Archive
 Usage with [internetarchive](https://github.com/jjjake/internetarchive) is the same as other libraries
 that subclass `requests.Session`:
@@ -62,7 +89,7 @@ that subclass `requests.Session`:
 ...     """Session with features from both CachedSession and ArchiveSession"""
 ```
 
-## Requests-mock
+## Requests-Mock
 [requests-mock](https://github.com/jamielennox/requests-mock) has multiple methods for mocking
 requests, including a contextmanager, decorator, fixture, and adapter. There are a few different
 options for using it with requests-cache, depending on how you want your tests to work.