🎨 Better UX for users migrating off Requests

Applied remarks collected from grafana-toolbox/grafana-client#146
and grafana-toolbox/grafana-wtf#130

docs/community/recommended.rst

@@ -6,14 +6,31 @@ Recommended Packages and Extensions
 Niquests is compatible with a great variety of powerful and useful third-party extensions.
 This page provides an overview of some of the best of them.
 
-CacheControl
-------------
+Requests Cache
+--------------
 
-`CacheControl`_ is an extension that adds a full HTTP cache to Niquests. This
-makes your web requests substantially more efficient, and should be used
-whenever you're making a lot of web niquests.
+`requests-cache`_ is a persistent HTTP cache that provides an easy way to get better performance with the python requests library.
 
-.. _CacheControl: https://cachecontrol.readthedocs.io/en/latest/
+.. _requests-cache: https://github.com/requests-cache/requests-cache
+
+.. warning:: There's a catch when trying to use Niquests with `requests-cache`_. You will need a quick patch prior to using it.
+
+Do as follow::
+
+    import requests_cache
+    import niquests
+
+
+    class CacheSession(requests_cache.session.CacheMixin, niquests.Session):
+        ...
+
+
+    if __name__ == "__main__":
+
+        s = CacheSession()
+
+        for i in range(60):
+            r = s.get('https://httpbin.org/delay/1')
 
 Requests-Toolbelt
 -----------------

src/niquests/sessions.py

@@ -1169,8 +1169,20 @@ def handle_upload_progress(
         # Start time (approximately) of the request
         start = preferred_clock()
 
-        # Send the request
-        r = adapter.send(request, **kwargs)
+        try:
+            # Send the request
+            r = adapter.send(request, **kwargs)
+        except TypeError:
+            # this is required because some people may do an incomplete migration.
+            # this will hint them appropriately.
+            raise TypeError(
+                "You probably tried to add a Requests adapter into a Niquests session. "
+                "Make sure you replaced the 'import requests.adapters' into 'import niquests.adapters' "
+                "and made required adjustment. If you did this to increase pool_maxsize, know that the "
+                "Session constructor support kwargs for it. "
+                "See https://niquests.readthedocs.io/en/latest/user/quickstart.html#scale-your-session-pool to learn more."
+            )
+
         # Make sure the timings data are kept as is, conn_info is a reference to
         # urllib3-future conn_info.
         request.conn_info = _deepcopy_ci(request.conn_info)
@@ -1329,6 +1341,15 @@ def mount(self, prefix: str, adapter: BaseAdapter) -> None:
 
         Adapters are sorted in descending order by prefix length.
         """
+        if not isinstance(adapter, BaseAdapter):
+            raise TypeError(
+                "You probably tried to add a Requests adapter into a Niquests session. "
+                "Make sure you replaced the 'import requests.adapters' into 'import niquests.adapters' "
+                "and made required adjustment. If you did this to increase pool_maxsize, know that the "
+                "Session constructor support kwargs for it. "
+                "See https://niquests.readthedocs.io/en/latest/user/quickstart.html#scale-your-session-pool to learn more."
+            )
+
         self.adapters[prefix] = adapter
         keys_to_move = [k for k in self.adapters if len(k) < len(prefix)]